2010/1/2 Russ Allbery <rra@debian.org>: > 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 [...] > >> I'm interested in helping out with this. [...] Please find attached lintian.dbk. It's the result of an automated conversion followed by some changes to make it * build, * use more specific tags where possible (e.g., <literal/> can be replaced with lots of different stuff for special things), * reinsert missing paragraph breaks, * re-add abstract and copyright/licensing info which got lost during conversion, * rename the file *.dbk instead of *.docbookxml. > 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. [...] > 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? I've attached used_tags.txt. It's basically lintian.dbk, but with only the first instance (pretty much) of each tag and not the global tags, e.g., <book/> and <abstract/>. In some sense, these 97 lines should be enough of a read to be able to produce more content in lintian.dbk that uses the same tags for the same purposes. Of course, once other kinds of markup is needed, this compilation becomes useless. used_tags.txt could be used as a rough start for a decent documentation and it may or may not be interesting to keep it as it is. Feedback: I'd love it! :) I believe used_tags.txt could be used to judge a lot of what I have done. lintian.dbk should hopefully be the same stuff over and over again. :) The output of docbook2html lintian.dbk docbook2txt lintian.dbk can be used to produce rough output, suitable for judging. As Osamu showed, there are other, better, ways of doing this step when we want a production build. Osamu, it seems you know way more about building than I do. Perhaps you could suggest exactly how to build this thing prettily, sort of like the dev-ref snippet you posted in another message? Take care, Martin
<chapter label="1" id="Chapter-1">
<title>Introduction</title>
<sect1 label="1.1" id="Section-1.1">
<title>About Lintian</title>
<para>...</para>
</sect1>
—
<para>Therefore, our policy is <emphasis>not</emphasis> designed to ...</para>
<itemizedlist mark="bullet">
<listitem>
<para>
...
</para>
</listitem>
</itemizedlist>
<orderedlist numeration="arabic">
<listitem>
<para>
...
</para>
</listitem>
</orderedlist>
<para>
... install the <systemitem role="package">lintian</systemitem> Debian package.
</para>
<para>After that, you can run Lintian over any Debian binary, udeb or source packages
like this:</para>
<screen>
$ lintian libc5_5.4.38-1.deb
E: libc5: old-fsf-address-in-copyright-file
W: libc5: shlib-without-dependency-information usr/lib/libgnumalloc.so.5.4.38
W: libc5: shlib-without-dependency-information lib/libc.so.5.4.38
W: libc5: shlib-without-dependency-information lib/libm.so.5.0.9
E: libc5: shlib-with-executable-bit lib/libc.so.5.4.38 0755
E: libc5: shlib-with-executable-bit lib/libm.so.5.0.9 0755
E: libc5: shlib-missing-in-control-file libgnumalloc usr/lib/libgnumalloc.so.5.4.38
$
</screen>
<para>The first character of each line indicates the type of
message. Currently, the following types are supported:</para>
<variablelist>
<varlistentry>
<term><emphasis>Errors (E)</emphasis></term>
<listitem>
<para>
The displayed message indicates a policy violation or a
packaging error. For policy violations, Lintian will cite the
..
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
The problem is identified by a so-called <emphasis>tag</emphasis> (for
example, <literal>old-fsf-address-in-copyright-file</literal>).
</para>
<para>
In some cases, the messages contain some additional text with a
leading hash character (<literal>#</literal>).
</para>
your packages using the <option>-d</option> (or <option>--debug</option>) option,
you have to place it at
<filename>/usr/share/lintian/overrides/<replaceable><package></replaceable></filename> inside the
package. If the override is for a source package, you have to place it
at <filename>debian/source/lintian-overrides</filename>
<para>The format of the overrides file is simple, it consists of one override per
line (and may contain empty lines and comments, starting with a <literal>#</literal>, on others):
<literal>[<replaceable><package></replaceable>[ <replaceable><type></replaceable>]: ]<replaceable><lintian-tag></replaceable>[
[*]<replaceable><lintian-info></replaceable>[*]]</literal>. <replaceable><package></replaceable> is the package name;
<replaceable><type></replaceable> is one of <literal>binary</literal>, <literal>udeb</literal> and
<literal>source</literal>, and <replaceable><lintian-info></replaceable> is all additional
information provided by Lintian except for the tag. What's inside brackets is
optional and may be omitted if you want to match it all.
two scripts, namely <command>lintian</command> and <command>lintian-info</command>
Lintian's laboratory directory can be defined via the <constant>LINTIAN_LAB</constant>
variable (either in the configuration file or as environment
variable).
Then, you have to run <command>lintian <option>-S</option></command> to set up the laboratory
After that, you can either check single packages simply be running
<screen>
$ lintian foo
</screen>
Attachment:
lintian.dbk
Description: Binary data