On Mon, 2006-08-28 at 00:59 +1000, Miles Brennan wrote:
I've been working on converting the server guide (slowly) and
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
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:
Here's my explanatory text about what happens
when you run the <command>foosetup</command>
command. First, the following screen appears:
<computeroutput>Your setup of foo
Then you can add the following line to the
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:
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.
Paul W. Frields, RHCE http://paul.frields.org/
gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233 5906 ACDB C937 BD11 3717
Fedora Project Board: http://fedoraproject.org/wiki/Board
Fedora Docs Project: http://fedoraproject.org/wiki/DocsProject