I wrote: > > I'd like to see a format where users would be encouraged to submit new > > documents that could easily be linked in to the documentation. I'd like > > to initially focus on generating on-line HTML (and text file) documentation. > > When we get a significant chunk of documentation written, then we can > > work on some other formats of documentation (like hardcopy) based on the > > content that we've already assembled. Christian Schwarz wrote: > I disagree here. Though I really don't like sgml much it seams to do a > very good job for the Linux HOWTO's as well as for our existing > documentation. > > I see the following main advantages: > > o you get several output formats at one time > o it very easy to have all documents us the same layout > o it's much easier to write the sgml code than to write html code > (you don't have to care about links, toc, etc.) > > I have one question about debiandoc-sgml. It was built by Ian some time > ago when he was working on the dpkg prog manual and the policy manual. It > was split from linuxdoc-sgml since he saw several disadvantages of the > latter. I think he was right that time. However, it seams to me as > sgml-tools (successor of linuxdoc-sgml) has been worked on much lately and > I don't think it is appropriate for Debian to maintain its own SGML > system! > > Susan, which system is your Debian FAQ based on? > > Another option would by hyperlatex. Note that I took over maintainership > of this package because noone else wanted to do it. I didn't like this > very much but it seams to be doing a _very_ good job. What about writing > all docs in LaTeX and creating a HTML version via hyperlatex? (I'm a TeX > fan(atic) :-) Well, I sort-of agree. I guess the point I was trying to make was that I've seen many huge flamewars on the 'net about what format the documentation should take. I think we could avoid this by accepting basic documentation in plain ascii text format -- and then we could plunk it into any format we wanted to. Typically, if you are writing an article for a magazine, you don't have to do the typesetting yourself -- you just submit your writing to an editor, who then sends it to a production crew that gets it ready for final printing. We should have a similar attitude here. I think that writing documentation for Debian should be as simple as posting it to this list -- and then someone will pick it up and put in the appropriate package, or format it for HTML, or do a really spiffy TeX layout. Personally, I really want to learn TeX, since it looks super useful -- but I don't want to have to learn it (or linuxdoc, or debiandoc) in order to write documentation for the project. Aside from actually creating an environment that encourages people to write good documentation -- we also do need to discuss what the interim, and final formats of the docs will look like, and how they will be organized. > Hey, I suspect we'll have much fun on this mailing list :-) Documentation, fun? Who woulda thunk? :-) Cheers, - Jim
Attachment:
pgpa3aMDuExOk.pgp
Description: PGP signature