Re: gnome-user-docs master

[Shaun McCance <shaunm gnome org>]

On Fri, 2011-09-16 at 18:12 +0300, Luc Pionchon wrote:
> On Fri, Sep 16, 2011 at 17:49, Shaun McCance <shaunm gnome org> wrote:
>         
>         Not freezing because it's not ready. There are 238 pages that
>         are
>         completely unreviewed for 3.2. Every page needs to be reviewed
>         for
>         technical accuracy, because software changes could affect any
>         one
>         of them.
> 
> 
> Would it be possible to flag the pages with their maturity level?
> 
> In such a way that it appears in the .po files.  
> So the translators would know what pages to focus on.
> 
> Something like
> - stub                  (dummy text)
> - draft                  (major change expected)
> - under rework    (some changes expected)
> - under review     (little changes expected)
> - final
> 
> I am thinking it could also appear on the rendered pages (maybe as a
> build time option), which would be fair play with the reader. And
> since it is public collaborative work, under-final flagged pages could
> link to a page explaining how to contribute.

We do mark statuses with the <revision> element in Mallard. The
statuses we use are documented here:

http://live.gnome.org/DocumentationProject/StatusTracking

You can see statuses with the yelp-check tool, which comes with
yelp-tools. For example:

  yelp-check status --pkgversion 3.2 .
  yelp-check status --pkgversion 3.2 --totals .

Use --help for more options. Blip also tracks these statuses:

http://blip.blip-monitor.com/doc/git.gnome.org/gnome-user-docs/gnome-help/master#pages

You can also run yelp with --editor-mode, and you'll see banners
and flags and other stuff that tell you page statuses.

Basically, the only thing that's missing is to put that maturity
information into the PO files. I could add a custom ITS rule to
gnome-help.its that would put the current status in a comment.
Something like this:

<its:locNoteRule
selector="/mal:page[mal:info/mal:revision
          [@status][@pkgversion='3.2']]//*"
locNotePointer="/mal:page/mal:info/mal:revision
                [@status][@pkgversion='3.2'][last()]/@status"/>

The results aren't quite as nice as you'd hope. I need to do some
work on locNote handling in itstool.

Better still would be if gettext & friends didn't destroy flags it
doesn't know about. Then I could add an itstool extension to put in
something like this:

#, status:final

So, yeah, our tools aren't *quite* good enough yet, but we're at least
on the right track to being able to do this cleanly.

--
Shaun