Re: Bits from the Lintian maintainers
Wow, two volunteers within a day! That's excellent. I'm replying to this
message since it goes into detail on the conversion process and copying
Osamu Aoki on this message. I'm not sure how easily the work can be
divided up -- maybe both of you can work out between each other how to
split things up?
Martin Ågren <martin.agren@gmail.com> writes:
> 2010/1/2 Russ Allbery <rra@debian.org>:
>> We're also looking for someone who would like to tackle converting the
>> Lintian manual to Docbook instead of DebianDoc-SGML and working on
>> updates. There's quite a bit about Lintian that isn't currently
>> documented. If you're interested, let us know.
> I'm interested in helping out with this. Having cloned the git repo
> and looked into the stuff in doc/, I have some initial observations
> and results and some questions to follow:
> With at least debiandoc-sgml, docbook-utils, docbook-xsl, and lynx
> installed, the following gives a good start:
> $cd doc
> $debiandoc2docbookxml lintian.sgml
> In the resulting file lintian.docbookxml, remove three or four lines
> relating to the pretty-much-empty chapter "Top". It is now possible to
> execute
> $docbook2html lintian.docbookxml
> and, similarly,
> $docbook2txt lintian.docbookxml
Oh, excellent. I didn't realize that the conversion could be largely
automated via debiandoc2docbookxml.
> This gives html and text versions pretty much as in debian/rules. Not
> exactly, though. There are some formatting differences and, more
> importantly, the abstract/copyright/authors information has
> disappeared in the sgml -> docbookxml process. Anyway, this could be a
> starting point for a more thorough, manual walk-through. So...
Yes, that makes sense.
> Am I correct in assuming doc/lintian.sgml and only that file is what
> is referred to in Russ' call for help above?
That's correct.
Currently, the Lintian manual is quite short. I'd like to expand it
considerably to include, for instance, more details about the internal
workings of Lintian and guidelines for contributors, instructions on how
to write a check script for people who want to add custom checks for their
packages, and so on. But it seemed like a good idea to convert the manual
format before doing much additional work.
> Since the toolchain is different, I'm guessing aesthetically different
> output is ok when comparing pre-conversion rendering with
> post-conversion rendering. That is, the aim is to convert the
> contents/semantics and leave the differences in the rendered output.
> (Surely there's a reason newer software produces different rendering.
> :) )
Correct.
> Would it be ok for me to "reserve" this work for myself, so that
> duplicate work is avoided? Would a couple of weeks be ok? I've got a
> life ;) but could do this on spare hours here and there.
The two of you are the people who have replied, so I think you can divide
the work up between yourselves however you see fit. If anyone else also
volunteers, I'll point them at you (and I'll update the wiki page
accordingly).
> Does a final lintian.docbookxml suffice, or would you prefer the result
> of an automated conversion followed by a series of patches? I'd use some
> VCS anyway, but if individual patches are favoured I'll try harder to
> keep them clean. :)
I'm okay either way on that. Whichever seems to make the most sense.
The one other thing that I'd like to have at the end of this process, in
addition to a converted file, is some pointer to where people who want to
add things to the manual can go to understand what markup tags to use.
One of the advantages of DebianDoc-SGML is that it's a fairly
straightforward markup system. Docbook is a huge language, and as someone
not horribly familiar with it, I admit to frequently getting lost in it
and not being sure which tag to use.
Is there a style guide that we could recommend? Would it make sense to
write a brief style guide for Lintian that points to tags that people are
most likely going to want to use?
Since we're converting the document fresh, would it make sense to move to
Docbook 5.0 instead of 4.5, on the assumption that 5.0 is eventually going
to relace 4.5?
--
Russ Allbery (rra@debian.org) <http://www.eyrie.org/~eagle/>
Reply to: