[Nut-upsdev] NUT Documentation project

[Arnaud Quette]

2007/6/4, Eric S. Raymond <esr at thyrsus.com>:
> 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.

I know. this is the major reason why the doc project never got results...

> 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.

though we're ok on the structured markup language, I've meanwhile
reconsidered the multi output capabilitilies, and so docbook.
Having html only suits me fine. So that might help in finding our
right solution...

Thus Charles solution (docutils) has to be considered. And I find it
really interesting, though I've not dug it... People are more and more
used to wiki style editing, still not to complex xml / sgml ones!

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

quite frankly, none of the above suits me since these either don't
allow easy edition (the wysiwyg can be the above mentioned "wiki
style" docutils one) or seems not complete enough nor perennial.

maybe a real wiki that allow html export?

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

well tangible wasn't the exact word. "...a major code contribution..."
would suit more my thought.
any other contributor that entered the team has made a lot of patches
before, allowing to validate his understanding of the project, its
standards and its aims.

this remark, along with the below one, are more intended to your
potential source code patches...

> > 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.

fine

> > - 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.

as told, I'll refrain from taking a decision for the moment.
I'd like us (you, Charles, me and others) to continue on checking the
possible solutions...
Any comment and feedback on the subject is welcome.

> > - 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.

don't hesitate to ask me any question you have according to that.
I know I've been either too verbose or not enough depending on the moment.
So the big picture about what I once called NUT-NG / NUT 3.0 might not
be as clear to others as to me...

-- Arnaud