Forum OpenACS Q&A: New package documentation
How should I go about doing that?
I'm assuming DocBook.
But the documentation should live under packages/workflow/www/doc, no?
How do I make that integrate with the rest of the docbook documentation, or how's that supposed to work?
What's a good example of a well-documented package? (Does one exist?)
Can some of our documentation gurus help point me in the right direction? :)
All of the stuff needed for OpenACS docbook stuff seems to be already installed on my Red Hat 8.0 install, except the chunk.xsl stylesheet isn't in /usr/share/sgml/docgook/stylsheet/xsl/nwalsh/html/chunk.xsl. Instead, it's in /usr/share/sgml/docbook/xsl-stylesheets/html/chunk.xsl, which also seems like a more logical place, given that it doesn't have the name of a particular author in there.
Or are there differences that mean I should go out and download the nwalsh version and use that instead?
Also, the tools mentioned on
doesn't mention htmldoc, which is required to generate PDF files (which is the default if you simply say 'make' in the packages/acs-core-docs/www/xml directory).
I've found a way out, however, namely W2XML, a thing that can convert Word documents to XML using a specific stylesheet, most notably DocBook.
So now I can use MS Word to write the doc, then convert it to DocBook. Neat. (Thanks, Mark, for the tip.)
Now the problem is that that converter only uses <section> tags, and not the <sect1>, <sect2>, etc., tags, that we tend to use.
Checking the reference at
it's clear that this should be just as fine. However, using our setup, each section gets the same size header, and the table of contents doesn't work.
Anybody have any idea why that would be and how to fix it?
If I were you, writing new documentation, I don't know if I'd go with Docbook. In fact, I've thought about converting our acs-core-docs from Docbook to something else several times (and I was the one encouraging ArsDigita to move the 4.x docs to Docbook way back when).
The reasons are simple... Docbook has all the whiz-bang and cool stuff, and a lot of people use it and all that, but it's just very hard to work with. It is very hard to be able to write a document quickly. There are a bunch of tools to install, a bunch of new, very verbose markup to learn, a bunch of settings to a bunch of places that need to be done.
In short, while it does everything one could imagine for documentation, unless you have someone with lots of Docbook experience/knowledge on board, the cost time-wise to climb that learning curve is so steep that nobody does it because nobody has time to and because documentation teams are seen as third-class citizens in the open source world (meaning you are rewarded for pumping out code, but if you pump out documentation that is seems as a clerical job without importance, so no one wants to get involved too much there).
What ends up happenning is that of the handful of people who are ok with being considered third-class citizens, only a few end up getting the courage to climb that learning curve, resulting in less documents or less updating of documents.
So I've thought about moving our documents to a format that's easier to work with, simpler, less complex, without such a learning curve, so that anyone could contribute docs in an easy manner. One of the formats I've thought of is APT (Almost Plain Text) which Ben Adida told me about a while ago.
Check that one out, too.
Even still, I think we should standardize on Docbook. It can be a pain to start using at first, but once the developer gets used to it is actually quite nice. I know for one of our projects the documentation writer was hesitant at first but by the end he was raving about the combination of Emacs and Docbook for writing a fairly large technical document.
The other day, I got my first taste of Docbook and at first would have agreed with you. I tried doing it by hand, and it was ridiculous. But after some searching, I found some good products and tools, like:
- jEdit This is a GPL XML editor that is built in Java and totally cross platform. It needs a fairly heavy duty processor (I'm running on a G4 400 and it was a wee bit slow) but it works really nicely. Tag autocompletion, XML tree views, etc. It's a really nice editor. And there are many, many plugins so it has a vibrant community.
- For OS X: Project Omega has a nice article about using Docbook on OS X. They also released a Docbook-X, a suite of tools to converting Docbook XML to HTML or PDF.
- For Windows: I haven't used e-notative Docbook Environment (eDE) for Windows because I'm not on a Win box, but they seem pretty comprehensive and I passed them on to a client. I used W2XML to convert a large Word doc to Docbook, and it worked nicely. But it created some really weird and dirty XML, as one might expect, that I had to go through by hand and clean up so that it could be managed and debugged easier.
- For Linux: I haven't researched this because I haven't needed to, but this Docbook wiki has a fairly comprehensive list of Docbook tools for all platforms.
I think that using jEdit plus some command line XSLT transforms is a good suggestion for documentation writers. It may be a bit painful at first, but ultimately I think we would be happier with the result.
Plus recommendations for tools that make it realistic, such as jEdit, make files, whatever.
Plus perhaps pick a package and make that one be documented according to the authorized documeentation standard.
That way we don't all have to spend hours investigating this field. If our documentation gurus could provide the framework, I'm sure more people would be encouraged to contribute. :)
It is very simple to modify the Docbook XSLT in W@XML to make <sect1> vs <section> tags. Simply modify the XSLT. Changing the section tags to sect1 tags is easy. Simply replace the following:
You may have to add a named style in word to pick up nested "sections", and detect this as a class attribute in the exported XML. For example, if you wanted to capture a style named "Heading4ArialNarrow" as your sect2's, then add the following to the Docbook XSLT:
<xsl:template match="h:p[attribute::class = 'Heading4ArialNarrow']">
The standard output from W2XML captures each style name and adds it as a class attribute value. It is easy to capture this and modify however you wish.
I've often wondered why we haven't made Wimpy Point our documentation standard. Obviously it lacks some key features and its a pain to write in HTML forms, but the gains could be great and it shouldn't be that hard to extend for our uses.
Here's an off-the-cuff idea of how it might work:
- openacs.org has a canonical location for each package's documentation which is an instance of the wimpy point (WP from here on) package, comments turned on
- if it doesn't already, WP should use the CR so that it has versioning
- WP should be extended to output several formats (HTML is easy, PDF, DocBook, or whatever) of an entire presentation (with or without comments, might be nice)
- when release time comes around for the package, mark the version of the documentation for that release and export in a convenient format
- add an import feature, so that people that don't want to copy and paste to html forms can write in emacs or whatever (surpise, surprise, I vote for being able to import the new Keynote XML format)
- add an "import/apply style sheet" to WP if it doesn't already have it
From where I stand the main benifit of DocBook is its automatic creation of navigation. Big deal. WP has a pretty straight forward interface for creating navigation. WP, provides an interface for multiple authors to work from the same place while maintaining version control and allowing comments. It has a low learning curve and is put together in a way that non-geeks can grok.
Last time I checked, we were developers of dynamic database backed websites. Let's eat our own dogfood.
Looking at that documentation, I was even comfortable starting to document in DocBook. I like Roberto's idea better though. Let's make it as easy to use as possible.
I'd even go for a Wiki.
The xsl or whatever translation didn't work for me, but I didn't follow his documentation step by step.
My own progress has been slow, but I'm working on longer term goals than the immediate documentation needs. Content first, then how to display it. I'll keep everyone posted when it is near publication.
Can you let us know which documentation you are working on. It will be better if effort is not duplicated.
Sorry if this seems vague. The writing is comprehensive. Were it to be duplicative or redundant and not read, I will be satisfied knowing that I will have gained a much greater understanding of the entire system and the implicit computer science principles that shape its core.
I'll send documents to you (and the current doc moderators) when they reach working-draft stage.
Pretty basic stuff, but I still like the idea of wimpy point being able to slurp up XML versions of presentations. Interestingly, if we add export to Keynote, a user could then use Keynote to export the WP presentation to Powerpoint.
OmniOutliner has numerous export options as well: