Hi Eric,<br><br>sorry for lagging, we're currently in the process of releasing the new NUT major release 2.4.0. Adding a few more new Debian packages on my side (powerman and pwrkap) and some huge Eaton corporate actions and personal stuffs, and my 48h/day are full...<br>
<br><div class="gmail_quote">2009/1/16 Eric S. Raymond <span dir="ltr"><<a href="mailto:esr@thyrsus.com">esr@thyrsus.com</a>></span><br><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">
Arnaud Quette <<a href="mailto:aquette.dev@gmail.com">aquette.dev@gmail.com</a>>:<br>
<div class="Ih2E3d">> first, a small sum up of the current status, past work and aims to<br>
> understand the situation:<br>
> - the doc need to be easily maintainable by a non tech guy (though I've<br>
> still not found anybody reliable enough for that),<br>
<br>
</div>This is a strong argument in favor of asciidoc for the in-tree<br>
documentation, which is by far the simplest text-formatting markup<br>
I've found yet. It's a fairly recently-developed technology; I did<br>
not know of it when we last had an in-depth conversation about this.<br>
<div class="Ih2E3d"></div></blockquote><div><br>indeed!<br> <br></div><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;"><div class="Ih2E3d">
> - we need to provide at least an html output,<br>
<br>
</div>asciidoc does a very good job at this. For a representative example of<br>
a document that includes a table, see<br>
<br>
<a href="http://www.catb.org/%7Eesr/wesnoth/campaign-design-howto.html" target="_blank">http://www.catb.org/~esr/wesnoth/campaign-design-howto.html</a><br>
<br>
Trickier styling is possible with CSS, but IMHO the default asciidoc<br>
styling is just fine, pleasingly light and elegant.<br>
<div class="Ih2E3d"><br>
> - many part of the contents of the website and inline doc (ie the docs/<br>
> directory of the source tree) are either redundant or missing on one side or<br>
> the other,<br>
> - considering all the above point, I started the<br>
> <a href="http://test.networkupstools.org" target="_blank">http://test.networkupstools.org</a> website, with a consolidated approach. This<br>
> is still a work underway though (or somewhat a failure!)<br>
<br>
</div>That doesn't look like a failure to me!</blockquote><div><br>it was more in the way "the final results are still not there"... and I've no real non tech people to catch this up.<br><br></div><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">
But I think you need to make<br>
a decision about design philosophy. There are two paths you can go down<br>
with different tradeoffs.<br>
<br>
One: Bring the website into the SVN tree as a branch. (And write a commit<br>
hook that propagates each page to the site whenever it's committed.)<br>
<br>
The disadvantage of this approach is that only people with dev access can<br>
add content to the site. The advantage is that integration with the in-tree<br>
documentation gets really easy.<br>
<br>
This is the approach we use in gpsd. It is appropriate for a project<br>
with a relatively small, tightly focused developer community and not<br>
much hope that outsiders will ever show up who are qualified to write<br>
docs but not to be core devs.<br>
<br>
Two: Make the website a wiki.<br>
<br>
This is the direction <a href="http://test.networkupstools.org" target="_blank">http://test.networkupstools.org</a> is going, of course.<br>
The advantage is that anyone can write and add NUT documentation. The<br>
disadvantage is that the in-tree documentation and the website will be<br>
in different markups, leading to different HTML styles, and there will<br>
be manual labor involved in moving stuff between the in-tree docs and<br>
the wiki or (especially) vice-versa.<br>
<br>
This is the approach we use in Battle For Wesnoth, which has a very large<br>
group of outside contributors (artists, campaign developers and so forth)<br>
who neither want nor should have dev access.<br>
<br>
Having worked extensively with both approaches, I think the in-tree<br>
one fits NUT's social dynamics better, but I would be willing to do it<br>
the other way if your judgement is otherwise.<br>
<div class="Ih2E3d"></div></blockquote><div><br>well, I've thought a bit about that in the past days, and I'm obviously going for #1 (in-tree).<br>but I think with a slight variation: a few pieces don't need (and even more, must not) be in the source tree. This is mostly the Homepage and Protocol library (== everything not under Documentation in the wiki ; I've started to reorganize this last with that idea in mind, but it's not finished).<br>
You can have an idea of this by mousing over the wiki menu...<br><br>The website is then a base container (homepage + menu) with pointers to the online documentation.<br><br>so I'm thinking about trimming it to that simple base. The wiki may then be superfluous (I'm hesitating due to i18n, which is another target), and a static set might do the trick.<br>
<br>we will need to talk / think a bit more to refine the final solution, but this looks really promising ^_^<br><br></div><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">
<div class="Ih2E3d">
> - the final system should fit the above, and allow to be used online (for<br>
> the website) and offline (for the source distribution and packages). It<br>
> should also allow a split between a User Manual, a Developer Manual,<br>
> - your above ASCIIDOC approach seems really interesting (and more than a raw<br>
> docbook approach!) and possibly meeting all the requirement.<br>
<br>
</div>Yes, it's a real improvement over DocBook -- almost all the power but<br>
with much lower front-end complexity.</blockquote><div><br>indeed, a real breakthrough ;-)<br><br>I'll postpone a bit more these discussions to concentrate on the various mentioned tasks. we can still continue to talk, but I won't be much responsive atm.<br>
<br>thanks again and cheers,<br>Arnaud</div></div>-- <br>Linux / Unix Expert R&D - Eaton - <a href="http://www.eaton.com/mgeops">http://www.eaton.com/mgeops</a><br>Network UPS Tools (NUT) Project Leader - <a href="http://www.networkupstools.org/">http://www.networkupstools.org/</a><br>
Debian Developer - <a href="http://people.debian.org/~aquette/">http://people.debian.org/~aquette/</a><br>Free Software Developer - <a href="http://arnaud.quette.free.fr/">http://arnaud.quette.free.fr/</a><br><br>