← Back to team overview

ubuntu-manual team mailing list archive

New LaTeX commands

 

Hello, everyone.

I've added a couple new LaTeX commands for us to use with the manual.

So far, we've been tracking the progress of the manual and the names
of the authors and editors through a spreadsheet. This involves a bit
of back-and-forth emails with all the authors and editors.

I thought that a better way would be to add a couple LaTeX commands so
that the authors/editors can note the status of their
chapters/sections themselves. One benefit of this is that I can then I
can have a program read those statuses automatically and update a web
page so everyone can see what the status is whenever they like.

Another problem is keeping track of who all has helped with the
manual. We haven't been doing as good of a job as we should with
updating the credits listing in the back of the manual. I've added a
new command so that the authors and editors can add their names to the
chapters/sections they're in charge of and we can use this information
to automatically update the credits listings in the back of the
manual.

Since it's late in this cycle, I don't expect everyone to start using
this commands right away, but you're welcome to if you like! I've
added the code to the bzr branch already, so the commands will work
right now. (I'm still writing the script to extract the status
information and the credits listings, but the manual will compile
successfully with these new commands in the meantime.)

First, the \credit command. Right now we track credits by comments at
the top of .tex files and by names listed in the spreadsheet.  Instead
of adding comments to the tops of the .tex files, we could add \credit
commands. Then we can have LaTeX automatically pull out the latest
credits from all the sections/chapters and put them in the Credits
section at the back of the manual.

    \credit{<type>}{<version>}{<name>}

For example, the prologue.tex file may have the following \credit lines:

    \credit{author}{10.04}{Benjamin Humphrey}
    \credit{author}{10.10}{Benjamin Humphrey}
    \credit{author}{11.10}{Mez Pahlan}
    \credit{author}{12.04}{Hannie Dumoleyn}
    \credit{author}{12.10}{Hannie Dumoleyn}
    \credit{author}{13.04}{Hannie Dumoleyn}
    \credit{editor}{12.04}{Paddy Landau}
    \credit{editor}{12.10}{Paddy Landau}

LaTeX would check for the credits applying to version 13.04 (since
that's the current version) of the manual to generate the credits
listing at the back of the book.

Next, the \status command.  This command specifies the latest status
of the current chapter/section:

    \status{13.04}{2013-04-13}{stub}
    \status{13.04}{2013-04-14}{incmplete}
    \status{13.04}{2013-04-15}{draft}
    \status{13.04}{2013-04-16}{outdated}
    \status{13.04}{2013-04-17}{review}
    \status{13.04}{2013-04-18}{candidate}
    \status{13.04}{2013-04-20}{final}

The first argument is the version of the manual. The second argument
is the date the \status command was added to the .tex file. The third
argument is the status of the manual. I borrowed the status words from
the Mallard markup language:

 * stub - contains little to no real content
 * incomplete - outline of all information, but lacking content
 * draft - all content available, but unpolished
 * outdated - was once complete or nearly complete, but needs to be
revised to reflect changes
 * review - ready to be reviewed by editors
 * candidate - reviewed and awaiting a final approval
 * final - approved and ready for publication or distribution

Then I can have a script read those status marks from the .tex files
and update a status board on our website so we can always see how
things are going. The authors/editors won't have to update the
spreadsheet, just update the .tex file as they work on it.

Finally, a third command I'm considering: the \version command. This
command is metadata that the authors and editors add so we can track
which version of a package/application has been documented:

    \version{firefox}{20.0+build1-0ubuntu0.12.10.3}

The first argument is the Ubuntu package name (the same name used with
apt-get). The second argument is the package version.

We could run a script to compare the versions documented with the
latest versions to see which packages have changed. Then have an idea
of which ChangeLogs we should read to see what changes have been made.
There should only be one \version command per package per
section/chapter. When you've updated the documentation to refer to the
newer version of the package, change the version number in the
\version command.

Let me know what you think of these new commands. Do you think they
will be helpful or will they just get in the way?  I'll work on
finishing up my status dashboard soon so we can see a status page on
our website and get an overview of our manuals.  The status page will
also include the status of screenshots and translations.

—Kevin Godby


Follow ups