ubuntu-manual team mailing list archive

[Tony Pursell <ajp@xxxxxxxxxxxxxxxxxxxxxxx>]

Hi Kevin

On 15 April 2013 05:31, Kevin Godby <godbyk@xxxxxxxxx> wrote:

> 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
>
>
>
> Look good.  Just two observations:

1. How is the 'approval' given to move from 'candidate' to 'final'? Who by?

2. \version will be difficult for me.  I have trouble working what package
is the appropriate one, let alone finding out full package names

Tony