[posted and mailed (by mistake] On Wed, 2008-02-06 at 12:08 +0100, Thomas Wehrspann wrote: > > > Of course, the real answer is to convert everything to docbook, then > > > generate "info" pages, manual pages and a printable manual from those, > > > but that's a lot of work... > > > > Anyone interested? I can provide support :) > Sure.
Glad to see this :) > Documenting is sort of fun. You can do it right away without understanding > the > code. Providing code for an existing project is much more difficult. > > So, what do you expect? > What should i convert/rewrite/merge into a new docbook documentation? > And what is the target version? transcode 1.0/1.1/head/...? the target is HEAD (so, 1.2.0 and later). In order to explain what I expect, let's paint the whole picture. The transcode documentation can be partitioned as follows: user documentation: - reference manual (man pages) - gotchas, quirks, hints (mostly on wiki) - tutorial/howto (mostly on wiki) developer documentation - reference manual (currently, almost everything we have is in comments) - design notes (a few in docs/tech) - tutorials/howto (uhm... :( ) docbook should fit all our needs almost flawlessly. Luckily enough, a fair part of documentation is (and should be in the near feature) autogenerable from source code (developer reference manual) or from the output of some tools (modules reference manual). I think the biggest problem is to have a tool or something that produces docbook sources from source code annotations (changing STYLE to conform to, say, doxygen is NOT an option today or in the near future; maybe this tool -and a small STYLE change, that should be feasible- www.naturaldocs.org) can help us. Another challenge is to have a tool that parses tcmodinfo output and produces suitable sources. Luckily enough, we can change tcmodinfo output quite a bit to make things easier; anyway this is NOT a short-term problem since we need NMS deployed first, so 1.2.0 or later. For 1.1.0 I'll brew something quick 'n' dirty and I'll use a custom format. To summarize, for the near future, I think the schedule is: - to convert transcode manpage (see below) to docbook - start to write design notes following the skeleton in docs/tech and source code (src/*) annotations. I can respond to any answer about the code and/or the design, but I have little to none time to write such doc. A word more about the transcode manpage; as stated before, it is in rewrittal by splitting out the modules portion. I'm attaching a preview of what we will have soon; as rule of thumb, cut out from current manpage the -x, -y paragraphes and the FILTERS section and you are 90% done. I think it's all. Questions? :) Bests, -- Francesco Romani // Ikitt [ Out of memory. ~ We wish to hold the whole sky, ~ But we never will. ]
transcode.1.gz
Description: GNU Zip compressed data
