On 2009-10-19 11:58, Andrew Beekhof wrote: > While I may be good at writing cluster software, I'm only average at > documenting it and suck horribly at making pretty web pages. > > Currently I use Pages.app (an Apple editor) for writing the docs because > it looks reasonable and lets me focus on the content. > However it uses an non-free format (preventing collaboration) and only > produces PDFs while it seems people desperately want clickable html pages. > > So, here's the deal... > > If anyone can make > http://hg.clusterlabs.org/pacemaker/stable-1.0/rev/1111462a3d67 > > Look something even remotely like > > http://www.clusterlabs.org/mediawiki/images/f/fb/Configuration_Explained.pdf > > > Then I will start using docbook for the documentation.[1] > > People that want a downloadable copy can have their PDFs, people that > want clickable html on the website can have that too, and we can include > an up-to-date version of either or both as part of each release. > > And anyone that feels included can help make it better. > > > Sound good? > > > Key criteria are: > - A style for commands such that they stand out from normal text > (possibly a slightly thicker fixed-width font)
Put those blocks in either <programlisting> or <literallayout> with <userinput> and <computeroutput>. Added bonus is that these preserve whitespace (so you can kill all those ugly <para> elements). Making these stand out is covered by my CSS -- which you already stole. :) > - A style for XML blocks such that they stand out from normal text > (fixed-width font with shaded background) <programlisting>. > - A style for output (fixed-width font with different shaded background > to XML) Either <programlisting> or <computeroutput>. > - Professional looking tables, instead of ones that look like they're > from 1995 For HTML this is pretty well covered. For FO is still sucks when using fop as your FO-to-PDF processor. I tend to refrain from tables as much as possible. > - Captions that are centered and stand out from the normal text <figure>, <equation>, <table> etc. all support <title>. <imageobject> supports <caption>. Look at the Pacemaker chapter in the DRBD docs for reference. > [1] Remember how much you didn't writing a few dozen lines of > configuration in XML? > Consider how unenthusiastic I might be to write massive slabs of text > with it ;-) > The XML for "Configuration Explained" alone is 4700 un-wrapped lines long. XML is a markup language, and it was created for documents, which it remains infinitely better suited for than for configuration files (where people really need to modify the markup -- it's perfectly OK to just use XML as an internal config format and have a sensible front end to modify it). So users do get to complain about having to hack markup. Tech writers do not. :) Cheers, Florian
signature.asc
Description: OpenPGP digital signature
_______________________________________________ Pacemaker mailing list Pacemaker@oss.clusterlabs.org http://oss.clusterlabs.org/mailman/listinfo/pacemaker
