Re: Splitting transcode(1) manpage

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