Re: Bits from the Lintian maintainers
Hi,
(I am noty yet subscribed. Plese CC me)
On Sat, Jan 02, 2010 at 11:34:53AM -0800, Russ Allbery wrote:
> 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?
There are not much work to split the work. Both I and Martin have
altready done conversion and question is more about how build script
should be shaped.
I think Martin Ågren understood the autoconversion script well and has done
hardwork part of manually touching up converted file. Thanks.
> 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".
This is one script which does auto conversion. (I took oner maintenance
of this package too.)
debiandoc2xml is another and I used it with "-1" option. (I wrote this script.
It did work fairly well but seems to need some manual tweek more.)
> 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.
It looks like Top is some bug.
I guess after xmllint, Martin's work is good to go.
> > 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.
Yes.
> > 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.
Yes. Since these scripts are not meant to be 100% bullet proof, they
are working to the level expected :-) Patches are welcome.
> > 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.
Martin's way of build will split out too many small html files. I guess
using some customization by calling xsltproc like Debian reference
(which was taken from d-i manual build script), can produce more
controlled output with different style.
---------
xsltproc --nonet --novalid --xinclude --stringparam root.filename index \
--stringparam base.dir /tmp/buildd/debian-reference-2.38/html/ \
--stringparam html.ext .fr.html \
--stringparam html.stylesheet debian-reference.css \
xslt/style-html.xsl debian-reference.fr.xml
----------
> > 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).
I do not have write access. Martin seems have done good manual work too.
Let Martin commit XML content first please.
> > 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.
In real life, people use only tags useful for building manuals. Actual
number of tags used are quite small.
(After auto conversion, we may need to convert few tags manually if you
want to be pedantic...)
> 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?
So following style of d-i manual or "developers reference" is good idea.
> 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?
What ever. It should be make no serious difference.
If I were you, I keep it as 4.5 since it is supported by lenny too.
Release of 5.0 just add it, I suppose.
Osamu
Reply to: