On Mon, 2006-08-28 at 00:59 +1000, Miles Brennan wrote:

I've been working on converting the server guide (slowly) and notice that the wiki does not have all the functionality/style that I need to 'easily' convert my guide to the LDP wiki - or I'm doing it the wrong way :-O.

As the guide is server based, most of the configuration is done by manually editing the files at the command line. I wanted to make the guide easy to follow, so I'd like to have a separate format/style differentiating between a typed command, the output of a command, and the contents of a configuration file - these seemed the most common choices for manual administration.

To move technical info (config files etc..) into the wiki takes a large amount of time using wiki markup, and displaying configuration files inside a table takes a fair bit to format, so it looks similar to what the user is expecting to see. To make it simpler, html - <PRE> tags work best, however the CSSs only provide one format/style for <PRE> tags.

This is exactly why using the Wiki is not the best way to do technical documentation. DocBook is far better suited, because there are tags to support all these different usages:

<para> Here's my explanatory text about what happens when you run the <command>foosetup</command> command. First, the following screen appears: </para> <screen> <computeroutput>Your setup of foo is complete.</computeroutput> </screen> <para> Then you can add the following line to the <filename>/etc/foo</filename> file: </para> <screen> <userinput>BAR=1</userinput> </screen>

The wiki has no good way of converting these elements once they're properly tagged with DocBook anyway. When we move to Plone, there may be a one-for-one conversion from DocBook in our CVS repository to the document in Plone -- or Plone might simply use the DocBook XML "live," converting user editing as necessary. I've no idea, unfortunately.

For now, simply use the technical terms and you'll have to rely on an editor to tag your guide correctly with DocBook -- or you could try doing it yourself, using some of the starter information I posted the other day in our inaugural Munch 'N' Learn:

http://www.redhat.com/archives/fedora-docs-list/2006-August/msg00081.html

DocBook is really very easy -- as easy as doing HTML or any other markup -- once you get started. Most people only ever use a handful of tags, and add more to their "personal knowledge base" as needed. XML is becoming (has become!) so widespread that it's almost criminal *not* to learn about it, and DocBook is just a specific type of XML document.