Re: gnome-user-docs master

[Luc Pionchon <pionchon luc gmail com>]

On Fri, Sep 16, 2011 at 21:27, Shaun McCance <shaunm gnome org> wrote:

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

This seems excellent!
 

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

(I did not know about blip. I wonder how it overlaps with DL)
 

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

I like the editor mode :)

I don't have yelp-tools, but checking with grep and wc,

$ ls *.page |wc -l
252
$ grep status=\" *.page |wc -l
29
$ grep status=\"final *.page |wc -l
18

So unless I am mistaken, out of 252 pages, only 29 has status property. I think a major issue now is that so little pages are stamped to be useful to translators. Are there any plans to update the status of the pages?

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

This would be great indeed
 

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.

I understand this.

I understand also that getting the whole process right isn't a trivial task and that it requires several iterations. Courage!