[Nut-upsdev] NUT Documentation project

[Eric S. Raymond]

Arnaud Quette <aquette.dev at gmail.com>:
> aren't there some bridge to docbook, from tex, odf, ... that would
> allow wysiwyg edition?

Not really.  And here you've run smack into the dilemma that afflicts
modern documentation-formatting toolchains.

On the one hand: There's a fundamental problem with such bridges.
ODF, TeX etc, have some structural features, like section headers, but
fundamentally they mark up documents at presentation level.  There isn't
enough structure in those formats to make good DocBook from them with
substantial human editing *every time you lift the document*.

On the other hand: You really need structural markup like DocBook to
do a good job of multimodal rendering (eg to to HTML, text, PDF).  So
your masters need to be in DocBook, or something equally structural.

Otherwise what you end up with is good rendering in some output
formats and crappy rendering in others, depending on which
presentational format you use as a master.  Awkardly, HTML, because
it's sort of half-structural, is generally one of the output
format that ends up looking *bad* when you do this -- and forget about
using CSS to fix it, either, because the structural hooks to hang 
CSS classes off won't be there.

The solution to this dilemma would be a powerful, capable WYSIWYG
editor that speaks DocBook (or some other structural format) natively.
Unfortunately, this is one of those deceptive problems that is not merely
hard but much harder than it looks.  There have been several attempts, and
all have failed.  (Even WYSIWIG editing of HTML is not really a solved
problem, and it is *much* less structural than DocBook.)

In the absence of such a tool, here are your options.  They're all bad in one
way or another.

(1) Write your own custom structural markup. In practice this means your own
XML DTD and stylesheets.  Advantage: you avoid the high complexity and
verbosity of DocBook.  Disadvantage: You maintain your own documentation
toolchain.  Forever.  You're screwed if you don't have an XSLT wizrd around.

(2) Accept the problems of keeping your masters in a presentational
markup like ODF.  Advantage: WYSIWIG.  Disadvantage: Multimodal
rendering will *suck*.  HTML is likely to be one of the losers.

(3) Bite the bullet and edit your masters in DocBook.  Advantage: 
Multimodal rendering works well (if you chose your toolchain carefully; 
some have a weakness near PDF).  Disadvantage: DocBook is sufficiently 
verbose and complex to be annoying to edit.

(4) Edit your masters in a less-powerful structural format like
asciidoc that lifts clean to a DocBook subset.  Still not WYSIWIG
but less annoying than editing DocBook directly.

I choose (3) when I can.  I prefer the control I get by editing DocBook 
directly.  (I've done two books this way.)

> Anyway, the aim is not to convert especially to docbook, but to have a
> system that allow easy and wysiwyg edition / maintenance, along with
> the generation of various output format (txt, html, pdf). Any clue?
> (Maybe Tex?! )

Not going to happen.  One of those objectives will have to be sacrificed; 
see above for explanation.  If you sacrifice WYSIWIG, we end up in 
DocBook-land; if you sacrifice multimodal rendering we might as
well write everything in HTML (but that would leave you with a problem
near man pages).

You can avoid DocBook, but anything you choose that is functionally
equivalent to it will have the same thorny relationship with
presentational formats.
 
> it will then depends on your results. if you have something tangible
> in a month, we can check for a backport.

Fine.
 
> >I'll need commit access to the repo and write access to the website.
> >I'm now esr-guest on alioth.
> 
> Welcome to the team.
> Though you have not yet produced tangible contribution proof, I
> believe that you will do soon.

Hey.  My version-number patch worked -- you saw the results in my trouble 
reports!

> For the moment:
> - read and conform to the NUT standards:
> http://svn.debian.org/wsvn/nut/trunk/docs/developers.txt?op=file&rev=0&sc=0

Done so.  None of the standards actually apply to a pure documentation project
except "supply man pages" which I generalize as "document what you do" and will
do.

> - create an esr_doc branch to work on the doc,
> - discuss all your changes to the trunk and other branches before
> commiting, and get the approval of the current team members, esp.
> Peter, Charles, Arjen and myself,
> - do not abuse of your svn access,

Befiore I do any actual changes, you need to decide among the available
bad choices for a documentation architecture.

> - read all my mails carefully, since I've already exposed the solution
> to the architecture and simplication things you've thrown (HAL / NUT
> NG and avahi, new configuration file format and tools, new doc, Nut
> Packaging Standard)!

Doing that.
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>