Re: Bits from the Lintian maintainers
2010/1/3 Osamu Aoki <osamu@debian.org>:
> On Sat, Jan 02, 2010 at 11:34:53AM -0800, Russ Allbery wrote:
[...]
> I think Martin Ågren understood the autoconversion script well and has done
> hardwork part of manually touching up converted file. Thanks.
I've gone through the document, adding information that went MIA and
changing some tags to more specific ones where possible.
> I guess after xmllint, Martin's work is good to go.
Tomorow, I'll give it another look and do an automated validation and
then it's hopefully good to go.
> Yes. Since these scripts are not meant to be 100% bullet proof, they
> are working to the level expected :-) Patches are welcome.
Osamu, I'd be glad to let you know exactly what I changed in the
output of the automated conversion, in case the things I encountered
are common enough to even warrant a patch.
> Martin's way of build will split out too many small html files.
Yes, I noticed that. I'll leave all of that for now and focus on the
document itself. Once everybody agrees on it, we can wreak havoc on
the different renderings. :)
>> 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. [...]
>
> I do not have write access.
Neither do I. :) This was not as time consuming as I thought so,
again, I hope I'll be done with the initial conversion tomorrow. I've
also noted some typos and other stuff which I'll save for later.
>> 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.
Yes, so far it's a pretty minimalistic document with just a handful of
reoccurring, non-trivial tags.
>> 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.
Agreed.
Martin
Reply to: