Wiki editing refresher

[Paul W. Frields]

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.

-- 
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
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
URL: <http://listman.redhat.com/archives/fedora-docs-list/attachments/20060827/8577ae41/attachment.sig>