[gentoo-doc] [RFC] Marking unmaintained documents

[gentoo-doc] [RFC] Marking unmaintained documents

[Jan Kundrát]

[-- Attachment #1: Type: text/plain, Size: 1518 bytes --]

Hi GDP-related entities,
as promised on IRC, here are my ideas about $SUBJECT.

Currently we have quite a lot of "unsupported"/"invalid"/"unmaintained"
documents for one of these reasons:

a) Third party article
b) Older Handbook
c) Translation in language which is not officially supported
d) Outdated translation

First three cases are easily detectable, fourth can't be checked easily
("what is outdated translation?"), AFAIK & IMHO.

So, the proposed change is to modify the XSL stylesheet to include some
bold red warning (with proper i18n, if possible) stating that the
document is no longer/not yet/... supproted, for example:

a) "This article is not part of the official Gentoo documentation, it
has been republished on our site only for your convenience and with
permisson of the respective copyright owner. It may not reflect current
state of things and could be outdated."

b) "This Handbook is no longer maintained and is left here only for your
convenience, please don't bother with submitting bugreports. In case you
are looking for networkless installation instructions, please consult
<link>current handbook</link>."

c) "This language is not backed up by an official Translation Team and
might be outdated or even incorrect. In doubts please consult
[link]original document[/link]."

Some random resources:
http://bugs.gentoo.org/show_bug.cgi?id=105248 - l-posix3.xml:
control_destroy() calls pthread_cond_destroy() twice

All opinions are welcome.

-jkt

-- 
cd /local/pub && more beer > /dev/mouth

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 256 bytes --]

Re: [gentoo-doc] [RFC] Marking unmaintained documents

[Xavier Neys]

Jan Kundrát wrote:
> Hi GDP-related entities,
> as promised on IRC, here are my ideas about $SUBJECT.
> 
> Currently we have quite a lot of "unsupported"/"invalid"/"unmaintained"
> documents for one of these reasons:
> 
> a) Third party article
> b) Older Handbook
> c) Translation in language which is not officially supported
> d) Outdated translation
> 
> First three cases are easily detectable, fourth can't be checked easily
> ("what is outdated translation?"), AFAIK & IMHO.
> 
> So, the proposed change is to modify the XSL stylesheet to include some
> bold red warning (with proper i18n, if possible) stating that the
> document is no longer/not yet/... supproted, for example:
> 
> a) "This article is not part of the official Gentoo documentation, it
> has been republished on our site only for your convenience and with
> permisson of the respective copyright owner. It may not reflect current
> state of things and could be outdated."

No need to hack the xsl for that, just add it at the beginning of each article 
like we already have the note about owners.

> b) "This Handbook is no longer maintained and is left here only for your
> convenience, please don't bother with submitting bugreports. In case you
> are looking for networkless installation instructions, please consult
> <link>current handbook</link>."

> c) "This language is not backed up by an official Translation Team and
> might be outdated or even incorrect. In doubts please consult
> [link]original document[/link]."

Can only be done with a reliable document location made available to the xsl 
which we lack at the moment.

I wish we could but at the moment, we can't really


-- 
/  Xavier Neys
\_ Gentoo Documentation Project
/  French & Internationalisation Lead
\  http://www.gentoo.org/doc/en
/\


-- 
gentoo-doc@gentoo.org mailing list

Re: [gentoo-doc] [RFC] Marking unmaintained documents

[Jan Kundrát]

[-- Attachment #1: Type: text/plain, Size: 1789 bytes --]

Xavier Neys wrote:
>> a) "This article is not part of the official Gentoo documentation, it
>> has been republished on our site only for your convenience and with
>> permisson of the respective copyright owner. It may not reflect current
>> state of things and could be outdated."
> 
> No need to hack the xsl for that, just add it at the beginning of each
> article like we already have the note about owners.

This implies manual changing of several files which is not good, IMHO.

>> b) "This Handbook is no longer maintained and is left here only for your
>> convenience, please don't bother with submitting bugreports. In case you
>> are looking for networkless installation instructions, please consult
>> <link>current handbook</link>."
>> c) "This language is not backed up by an official Translation Team and
>> might be outdated or even incorrect. In doubts please consult
>> [link]original document[/link]."
> 
> 
> Can only be done with a reliable document location made available to the
> xsl which we lack at the moment.
> 
> I wish we could but at the moment, we can't really

Well, I think that fixing <guide path="..."> that does'nt contain
directory name is easier than adding some disclaimer to every file and
could be done by a script (haven't tried, though). And it wouldn't
matter if we didn't catch every outdated/unmaintained/... document, but
at least some of them will be marked.

So, is there any problem to check the value of the path attribute
(provided it includes the directory name) against some regexp and if it
matches, add some warning to the generated page?

Maybe also introduce another parameter to metadoc saying "this
translation is outdated", but I'm not sure if this is worth the effort.

Cheers,
-jkt

-- 
cd /local/pub && more beer > /dev/mouth

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 256 bytes --]

Re: [gentoo-doc] [RFC] Marking unmaintained documents

[Xavier Neys]

Jan Kundrát wrote:
> Xavier Neys wrote:
> 
>>>a) "This article is not part of the official Gentoo documentation, it
>>>has been republished on our site only for your convenience and with
>>>permisson of the respective copyright owner. It may not reflect current
>>>state of things and could be outdated."
>>
>>No need to hack the xsl for that, just add it at the beginning of each
>>article like we already have the note about owners.
> 
> This implies manual changing of several files which is not good, IMHO.

Why? We change a small number of docs once, then forget about them.
Do you think it is better to introduce more code, more complexity to be 
maintained, more stuff to be executed on each and every doc request?
Is that your definition of better?

>>Can only be done with a reliable document location made available to the
>>xsl which we lack at the moment.
>>
>>I wish we could but at the moment, we can't really
> 
> Well, I think that fixing <guide path="..."> that does'nt contain
> directory name is easier than adding some disclaimer to every file and
> could be done by a script (haven't tried, though). And it wouldn't
> matter if we didn't catch every outdated/unmaintained/... document, but
> at least some of them will be marked.

If we mark some files as unmaintained, we're also telling our users that 
non-marked files *are* maintained.

> So, is there any problem to check the value of the path attribute
> (provided it includes the directory name) against some regexp and if it
> matches, add some warning to the generated page?
> 
> Maybe also introduce another parameter to metadoc saying "this
> translation is outdated", but I'm not sure if this is worth the effort.

You should try to think about feasibility, implementation & consequences first.


/me comes back on Monday.
Have a nice weekend,
-- 
/  Xavier Neys
\_ Gentoo Documentation Project
/  French & Internationalisation Lead
\  http://www.gentoo.org/doc/en
/\


-- 
gentoo-doc@gentoo.org mailing list

Re: [gentoo-doc] [RFC] Marking unmaintained documents

[Jan Kundrát]

[-- Attachment #1: Type: text/plain, Size: 987 bytes --]

Xavier Neys wrote:
>> This implies manual changing of several files which is not good, IMHO.
> 
> 
> Why? We change a small number of docs once, then forget about them.
> Do you think it is better to introduce more code, more complexity to be
> maintained, more stuff to be executed on each and every doc request?
> Is that your definition of better?

I'm not familiar with inner workings of gorg/axkit and I don't know
anything about speed issues or expensiveness of XML transformations, sorry.

> If we mark some files as unmaintained, we're also telling our users that
> non-marked files *are* maintained.

Good point, but IMHO we are now telling that *everything* is maintained
("file is on gentoo.org -> it's official").

> You should try to think about feasibility, implementation & consequences
> first.

That's why I included "[RFC]" in the subject. I don't know if it is
possible and worth the effort, I'm just asking.

Cheers,
-jkt

-- 
cd /local/pub && more beer > /dev/mouth

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 256 bytes --]

Re: [gentoo-doc] [RFC] Marking unmaintained documents

[Shyam Mani]

[-- Attachment #1: Type: text/plain, Size: 467 bytes --]

Jan Kundrát wrote:

> Good point, but IMHO we are now telling that *everything* is maintained
> ("file is on gentoo.org -> it's official").

Well, not exactly....there is a last updated thingy...so something
written in 2004 might not exactly be updated.

And yeah, gentoo.org -> official *always* holds, no matter if it's
updated or not.

Regards,

-- 
Shyam Mani | <fox2mike@gentoo.org>
docs-team  | http://gdp.gentoo.org
GPG Key    | 0xFDD0E345


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 189 bytes --]

Re: [gentoo-doc] [RFC] Marking unmaintained documents

[Sven Vermeulen]

[-- Attachment #1: Type: text/plain, Size: 900 bytes --]

On Fri, Sep 09, 2005 at 12:34:24AM +0530, Shyam Mani wrote:
> Well, not exactly....there is a last updated thingy...so something
> written in 2004 might not exactly be updated.

This is actually a point of discussion I had with Xavier (well, discussion,
he mentioned it before he went away :). You can change the date of the
document when you fix a stupid typo without auditing the rest of the
document for its accuracy. That might result in a inaccurate document 
with a recent date.

Or you can resist the temptation of changing the date, yielding a perhaps
perfectly accurate and well-written document with an old date.

Wkr,
      Sven Vermeulen

-- 
  Gentoo Foundation Trustee          |  http://foundation.gentoo.org
  Gentoo Documentation Project Lead  |  http://www.gentoo.org/proj/en/gdp
  Gentoo Council Member  

  The Gentoo Project   <<< http://www.gentoo.org >>>

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

Re: [gentoo-doc] [RFC] Marking unmaintained documents

[Sven Vermeulen]

[-- Attachment #1: Type: text/plain, Size: 2281 bytes --]

On Thu, Sep 08, 2005 at 08:12:08PM +0200, Jan Kundrát wrote:
> I'm not familiar with inner workings of gorg/axkit and I don't know
> anything about speed issues or expensiveness of XML transformations, sorry.

Now that's an interesting subject for documents: performance analysis on
Gentoo :) Would actually constitute an entire category of documents ! =)

> > If we mark some files as unmaintained, we're also telling our users that
> > non-marked files *are* maintained.
> 
> Good point, but IMHO we are now telling that *everything* is maintained
> ("file is on gentoo.org -> it's official").

We are now telling that the documents on the site are up for improvements.
Think about what we do with bugreports about /proj/en/* documents - we tell
them the GDP can't fix those and redirect them to the appropriate team.

What would you do with a bugreport about a totally different site? Right,
giggle a bit, tell the world about the stupid bug report and mark it as
wontfix/cantfix.

Now what would you do with a bugreport about a document that /is/ in
/doc/en? You'll either try to fix the document, or keep the bugreport until
someone else can fix it. What's wrong with this? In the worst case, the
bugreports for a particular guide are piling up with the net end result that
we remove the document from CVS (well, Attic it or move it somewhere else).

If we would mark documents as "outdated"/"unmaintained" and you'll get a
bugreport about those, what would you do differently from bugreports on
documents that are up-to-date/maintained? I would be quite surprised if you
handled those bugs differently.

> That's why I included "[RFC]" in the subject. I don't know if it is
> possible and worth the effort, I'm just asking.

I like it. Gives some action on the mailinglist again. I almost thought I
would lose my English skills if it went on like this (no IRC, no English
phone calls, hardly any mailinglist traffic - except on stupid or off-topic
... err ... topics :)

Wkr,
      Sven Vermeulen

-- 
  Gentoo Foundation Trustee          |  http://foundation.gentoo.org
  Gentoo Documentation Project Lead  |  http://www.gentoo.org/proj/en/gdp
  Gentoo Council Member  

  The Gentoo Project   <<< http://www.gentoo.org >>>

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

Re: [gentoo-doc] [RFC] Marking unmaintained documents

[Jan Kundrát]

[-- Attachment #1: Type: text/plain, Size: 771 bytes --]

Sven Vermeulen wrote:
> If we would mark documents as "outdated"/"unmaintained" and you'll get a
> bugreport about those, what would you do differently from bugreports on
> documents that are up-to-date/maintained? I would be quite surprised if you
> handled those bugs differently.

Well, my aim was to prevent bugreports for docs that are "no longer
maintained" like articles and old Handbooks (but I got a bit confused
and probably thought that old HBs contain all sections without new
bugfixes which is not true).

However, I think that we can make add some warning/disclaimer to the
republished articles. And an easy way to allow Lead Translator to make
some document marked as "obsolete" would be worth too, IMHO.

-jkt

-- 
cd /local/pub && more beer > /dev/mouth

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 256 bytes --]

Re: [gentoo-doc] [RFC] Marking unmaintained documents

[Sven Vermeulen]

[-- Attachment #1: Type: text/plain, Size: 767 bytes --]

On Sat, Sep 10, 2005 at 03:10:49PM +0200, Jan Kundrát wrote:
> Well, my aim was to prevent bugreports for docs that are "no longer
> maintained" like articles and old Handbooks (but I got a bit confused
> and probably thought that old HBs contain all sections without new
> bugfixes which is not true).

If no-one would report bugs on unmaintained documents, we would never be
able to fix them unless we totally relie on ourselves.

Better would be to /do/ have multiple bugreports on it :)

Wkr,
      Sven Vermeulen

-- 
  Gentoo Foundation Trustee          |  http://foundation.gentoo.org
  Gentoo Documentation Project Lead  |  http://www.gentoo.org/proj/en/gdp
  Gentoo Council Member  

  The Gentoo Project   <<< http://www.gentoo.org >>>

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

Re: [gentoo-doc] [RFC] Marking unmaintained documents

[Jan Kundrát]

[-- Attachment #1: Type: text/plain, Size: 309 bytes --]

Sven Vermeulen wrote:
> If no-one would report bugs on unmaintained documents, we would never be
> able to fix them unless we totally relie on ourselves.
> 
> Better would be to /do/ have multiple bugreports on it :)

Including third-party articles?

Cheers,
-jkt

-- 
cd /local/pub && more beer > /dev/mouth

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 256 bytes --]

Re: [gentoo-doc] [RFC] Marking unmaintained documents

[Sven Vermeulen]

[-- Attachment #1: Type: text/plain, Size: 1090 bytes --]

On Sat, Sep 10, 2005 at 10:26:37PM +0200, Jan Kundrát wrote:
> > Better would be to /do/ have multiple bugreports on it :)
> 
> Including third-party articles?

Why not? If the reports are valid and can be fixed with the historical
meaning in tact (i.e. the bugreport would also be valid at the time the
article was originally written), we should do so.

If the article is outdated but not wrong, we can have the bugreport marked
as LATER.

If the article is outdated and wrong, we can have the bugreport marked as
LATER and hope that someone would write a new article that "includes" the
fixes in the before mentioned bug reports. 

Even if no-one ever writes a follow-up on the article, we would still have
knowledge about the issues with the current article and, if needed, take
appropriate measures. 

Wkr,
      Sven Vermeulen

-- 
  Gentoo Foundation Trustee          |  http://foundation.gentoo.org
  Gentoo Documentation Project Lead  |  http://www.gentoo.org/proj/en/gdp
  Gentoo Council Member  

  The Gentoo Project   <<< http://www.gentoo.org >>>

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

Re: [gentoo-doc] [RFC] Marking unmaintained documents

[Jan Kundrát]

[-- Attachment #1: Type: text/plain, Size: 282 bytes --]

Sven Vermeulen wrote:
> Even if no-one ever writes a follow-up on the article, we would still have
> knowledge about the issues with the current article and, if needed, take
> appropriate measures. 

Okay, point taken :-).

Cheers,
-jkt

-- 
cd /local/pub && more beer > /dev/mouth

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 256 bytes --]

Re: [gentoo-doc] [RFC] Marking unmaintained documents

[Alexey Chumakov]

Hi GDPers,

Xavier Neys wrote:
> Jan Kundrát wrote:
> 
>> Hi GDP-related entities,
>> as promised on IRC, here are my ideas about $SUBJECT.
>>
>> Currently we have quite a lot of "unsupported"/"invalid"/"unmaintained"
>> documents for one of these reasons:
>>
>> a) Third party article
>> b) Older Handbook
>> c) Translation in language which is not officially supported
>> d) Outdated translation
[...]

After some extensive work with mostly outdated Russian docs, I tend to
agree with Jan--we need some means to signal an outdated translation.

My proposition is somewhat simpler --

1. Let the reader decide if the document is outdated :-)
We'll need to link the derived document to source one, and add a
displayed message:
"Source document is available at [link]
[optional version - fetched from source doc if possible
[optional date]"

Attr might look like this:
<guide link="/doc/ru/sample.xml" lang="ru" source-link="/doc/en/sample.xml">

Or, maybe it'll be possible to fetch dependency info from metadoc...

2. It's also useful to introduce some link like "send comments here..."
directly into document, and point it to GDP [internalization] page in
the document's language.
E.g. many Russian readers do not realize easily where to post their bug
reports and suggestions...

3. For unofficial languages, IMHO there is no need to do anything if
there's no index reference to it.
And 3rd party articles are already marked :-)

How do you like this idea?


WKR,
Alexey Chumakov
-- 
gentoo-doc@gentoo.org mailing list

Re: [gentoo-doc] [RFC] Marking unmaintained documents

[Jan Kundrát]

[-- Attachment #1: Type: text/plain, Size: 1725 bytes --]

Alexey Chumakov wrote:
> After some extensive work with mostly outdated Russian docs, I tend to
> agree with Jan--we need some means to signal an outdated translation.
> 
> My proposition is somewhat simpler --
> 
> 1. Let the reader decide if the document is outdated :-)
> We'll need to link the derived document to source one, and add a
> displayed message:
> "Source document is available at [link]
> [optional version - fetched from source doc if possible
> [optional date]"
> 
> Attr might look like this:
> <guide link="/doc/ru/sample.xml" lang="ru" source-link="/doc/en/sample.xml">
> 
> Or, maybe it'll be possible to fetch dependency info from metadoc...

Well, I asked about something similar (maybe completely different - I
don't know XSLT much) - use <uri link="metadoc:file-id"> and
automatically select translated file if available. I was told that it is
not easy and (iirc) can't be done ATM. Would be great, though :-).

> 2. It's also useful to introduce some link like "send comments here..."
> directly into document, and point it to GDP [internalization] page in
> the document's language.
> E.g. many Russian readers do not realize easily where to post their bug
> reports and suggestions...

IMHO useless, but I'm not typical Russian reader :-)

> 3. For unofficial languages, IMHO there is no need to do anything if
> there's no index reference to it.

Well, but what if previously supported language transformes into
unsupported one? There will be some links from non-official websites
pointing to the outdated translations...

> And 3rd party articles are already marked :-)

IIRC, articles themselves are *not* marked, only the index is.

Cheers,
-jkt


-- 
cd /local/pub && more beer > /dev/mouth

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 256 bytes --]

Re: [gentoo-doc] [RFC] Marking unmaintained documents

[Łukasz Damentko]

Hi,

On Fri, 09 Sep 2005 01:00:27 +0400
Alexey Chumakov <achumakov@gmail.com> wrote:

> After some extensive work with mostly outdated Russian docs, I tend to
> agree with Jan--we need some means to signal an outdated translation.
> 
> My proposition is somewhat simpler --
> 
> 1. Let the reader decide if the document is outdated :-)

Do we need so? It's easy to see in overview.xml page whether it's rusty
translation or not. For me there's no need to employ users to do
that... 

> 2. It's also useful to introduce some link like "send comments here..."
> directly into document, and point it to GDP [internalization] page in
> the document's language.
> E.g. many Russian readers do not realize easily where to post their bug
> reports and suggestions...

Could be
http://bugs.gentoo.org/enter_bug.cgi?product=Docs-user&component=Translated%20Documentation&short_desc=[$LANG
from <guide>] - to point them directly to reporting page.
Possible drawback could be abuse of that and rain of silly bugs.
It's also worth to note that not every reader is signed up to bugzie
and wants/has time to be...

> 3. For unofficial languages, IMHO there is no need to do anything if
> there's no index reference to it.
> And 3rd party articles are already marked :-)

Many times they are linked from third-party pages, sometimes are
bookmarked, so on, don't think that if they aren't in index, they
won't be noticed...

Summarising: I like the idea of some sort of "If you notice a bug,
please <uri link="somwhere in bugzie">let us</uri> know". It could be
somewhere near current abstract and date fields...

with regards,

Łukasz Damentko

--
polish lead translator
-- 
gentoo-doc@gentoo.org mailing list

Re: [gentoo-doc] [RFC] Marking unmaintained documents

[Flammie Pirinen]

2005-09-08, Jan Kundrát sanoi, jotta:

> a) Third party article
> b) Older Handbook

I really think that these could be done with static note inserted in
the code, because whatever program logic you could be thinking for
them it will always be multiple order more complex than needed. If you
want something easily automagically translatable you could introduce
something like <thirdparty/> and <obsolete/> empty (replaced) elements
in style of <license/>, no?

> c) Translation in language which is not officially supported

I wouldn't do anything with this, unless it intersects with d). I mean,
why would we need to tell our users that otherwise up-to-date document
should not be trusted to, just because the related translation team is
not organized with proper bureaucratic structure.

> d) Outdated translation

This is one really required improvement of this proposal, but it
relates to bigger part of desperately needed accessibility improvements
in whole translation system anyways. One of the biggest problems I get
reported for Finnish docs is that finding the corresponding English doc
is PITA (not everyone is comfortable with hacking the address line of
browser, after all). What would really be needed to solve situation
(and has been asked by community a thousand times) is language
negotiation of translated documents, and because of how language
negotiation algorithm works, it could easily be modified to take
outdatedness of translation in to account as qs-value, this way we
could serve up-to-date enough version to user in language he
understands even if it isn't native language or English. 

Of course on top of that we still do really need full interlanguage
linking web for all documents, and not just the for two index pages we
have. 

After these basics are in order, we might want to start looking in to
peeking original versions of document to see how up to date it is. By
the way, why can't this be done same way as in overview.xml? Because
AFAICS metadoc.xml in Finnish, for example, has only link to either
English or Finnish version, so the xslt must use some logic to fetch
english versions here, no? And if the logic is to pull the stuff from
English metadoc by matching id, shouldn't we then just resolve this by
adding a matching id to the root elements of the documents, which is
something that from semantic pov should've been done from beginning on
already. Of course this'd add overhead of loading (document()ing?) the
metadoc for all pageloads...

-- 
Flammie, Gentoo Linux Documentation's Finnish head translator.
<http://dev.gentoo.org/~flammie>
-- 
gentoo-doc@gentoo.org mailing list

Re: [gentoo-doc] [RFC] Marking unmaintained documents

[Alexey Chumakov]

Flammie Pirinen пишет:
> 2005-09-08, Jan Kundrát sanoi, jotta:
>>d) Outdated translation
[...]
> After these basics are in order, we might want to start looking in to
> peeking original versions of document to see how up to date it is. By
> the way, why can't this be done same way as in overview.xml? Because
> AFAICS metadoc.xml in Finnish, for example, has only link to either
> English or Finnish version, so the xslt must use some logic to fetch
> english versions here, no? And if the logic is to pull the stuff from
> English metadoc by matching id, shouldn't we then just resolve this by
> adding a matching id to the root elements of the documents, which is
> something that from semantic pov should've been done from beginning on
> already. Of course this'd add overhead of loading (document()ing?) the
> metadoc for all pageloads...
> 
Using the link in the document itself ls like any decentralized way:
+ efficiency -- no need to parse metadoc for each page
+ reliability -- no broken links on metadoc failure
+ flexibility -- works with non-metadoc project docs
- human factor -- document maintainer is responsible for the link
- need to update path in several places if source moves

To deal with '-', we need to:
maintain personal responsibility for maintainers (actually
self-maintained in our case, isn't it?)
simply accept the need to update path -- it's already there :-)


Using metadoc, the pros are:
+ clearness for the lead translator (...or actually not?)
+ simplicity of batch update (isn't often?
Cons are the opposite.

Are we centralized or not? :-)

Wkr,
Alexey
-- 
gentoo-doc@gentoo.org mailing list

Re: [gentoo-doc] [RFC] Marking unmaintained documents

[Jan Kundrát]

[-- Attachment #1: Type: text/plain, Size: 821 bytes --]

Alexey Chumakov wrote:
> Using the link in the document itself ls like any decentralized way:
> + efficiency -- no need to parse metadoc for each page
> + reliability -- no broken links on metadoc failure
> + flexibility -- works with non-metadoc project docs
> - human factor -- document maintainer is responsible for the link
> - need to update path in several places if source moves

- redundance -- exactly same information is duplicated in several places

> Using metadoc, the pros are:
> + clearness for the lead translator (...or actually not?)
> + simplicity of batch update (isn't often?
> Cons are the opposite.
> 
> Are we centralized or not? :-)

/me is by no means XML guru, but I always thought that metadoc.xml was
made for something like that...

Cheers,
-jkt

-- 
cd /local/pub && more beer > /dev/mouth

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 256 bytes --]

Re: [gentoo-doc] [RFC] Marking unmaintained documents

[Jan Kundrát]

[-- Attachment #1: Type: text/plain, Size: 1922 bytes --]

Flammie Pirinen wrote:
> I really think that these could be done with static note inserted in
> the code, because whatever program logic you could be thinking for
> them it will always be multiple order more complex than needed. If you
> want something easily automagically translatable you could introduce
> something like <thirdparty/> and <obsolete/> empty (replaced) elements
> in style of <license/>, no?

Seems reasonable. And I vote for that extra tag and not yet another
<warn>...</warn>.


>>c) Translation in language which is not officially supported
> 
> 
> I wouldn't do anything with this, unless it intersects with d). I mean,
> why would we need to tell our users that otherwise up-to-date document
> should not be trusted to, just because the related translation team is
> not organized with proper bureaucratic structure.

Well, current practice is that neysx commits every translation if it
seems to be ok from the XML point of view, but I'm not sure if it is a
good think to say that such docs are "official" - purely technically,
they were contributed by non-Gentoo person and we have no guarantee that
they are correct.

Just my 2 cents, of course - I'm not aware of any troubles caused by
this approach, so maybe I'm just too paranoic :-).

>>d) Outdated translation
> 
> 
> This is one really required improvement of this proposal, but it
> relates to bigger part of desperately needed accessibility improvements
> in whole translation system anyways.
[...]

I asked for the same while ago and was told that it is "not possible" or
at least "not so easy". BTW, see GLEP 10 [1].

[...]
> After these basics are in order, we might want to start looking in to
> peeking original versions of document to see how up to date it is.
[...]

This raises a problem about "what is outdated"?


Cheers,
-jkt

[1] - http://www.gentoo.org/proj/en/glep/glep-0010.html

-- 
cd /local/pub && more beer > /dev/mouth

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 256 bytes --]

Re: [gentoo-doc] [RFC] Marking unmaintained documents

[Flammie Pirinen]

2005-09-09, Jan Kundrát sanoi, jotta:

> Flammie Pirinen wrote:
> 
> Well, current practice is that neysx commits every translation if it
> seems to be ok from the XML point of view, but I'm not sure if it is a
> good think to say that such docs are "official" - purely technically,
> they were contributed by non-Gentoo person and we have no guarantee
> that they are correct.
> 
> Just my 2 cents, of course - I'm not aware of any troubles caused by
> this approach, so maybe I'm just too paranoic :-).

I was more thinking of Finnish team's situation where there aren't full
team to back things up but just a head translator. Tagging those docs
that _are_ up-to-date as non-official will just scare more people away.

> > 
> > This is one really required improvement of this proposal, but it
> > relates to bigger part of desperately needed accessibility
> > improvements in whole translation system anyways.
> 
> I asked for the same while ago and was told that it is "not possible"
> or at least "not so easy". BTW, see GLEP 10 [1].

Yeah, I remember GLEP 10 faintly, the problem of whole GLEP is that it
has no actually merits IMO. It just suggests something that might be
done to improve something, yet even without describing how it would
improve. AFAICT it doesn't help at all with linking things but makes
just some more work for even the current stuff.

The whole GLEP seriously rethought and rewritten might cut it, but it
again requires someone to do it :-)

> This raises a problem about "what is outdated"?

Nah, we'll just define some absolute value that is fully arbitrary and
stick with. Like those already in doc-policy.

-- 
Flammie, Gentoo Linux Documentation's Finnish head translator.
<http://dev.gentoo.org/~flammie>
-- 
gentoo-doc@gentoo.org mailing list

Re: [gentoo-doc] [RFC] Marking unmaintained documents

[Łukasz Damentko]

> > This raises a problem about "what is outdated"?
> 
> Nah, we'll just define some absolute value that is fully arbitrary and
> stick with. Like those already in doc-policy.

Translators Policy [1] clearly states how much can certain docs lag
from original to be considered outdated. As for info, we can always put
information "This translation went oudated due to lack of resources
inside GDP team, if you want to maintain this doc just <mail
link="$LANG lead translator">let us</mail> know". It could encourage
users to take care about documentation...

[1]
http://www.gentoo.org/proj/en/gdp/doc/translators-howto.xml#doc_chap3

with regards,

Łukasz Damentko

-- 
polish lead translator
-- 
gentoo-doc@gentoo.org mailing list

Re: [gentoo-doc] [RFC] Marking unmaintained documents

[Jan Kundrát]

[-- Attachment #1: Type: text/plain, Size: 569 bytes --]

Łukasz Damentko wrote:
> Translators Policy [1] clearly states how much can certain docs lag
> from original to be considered outdated. As for info, we can always put
> information "This translation went oudated due to lack of resources
> inside GDP team, if you want to maintain this doc just <mail
> link="$LANG lead translator">let us</mail> know". It could encourage
> users to take care about documentation...

I'd link to bugzilla or mailing list because the LT him|herself could be
very busy.

-jkt

-- 
cd /local/pub && more beer > /dev/mouth


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 256 bytes --]

Re: [gentoo-doc] [RFC] Marking unmaintained documents

[Sven Vermeulen]

[-- Attachment #1: Type: text/plain, Size: 2921 bytes --]

On Thu, Sep 08, 2005 at 06:56:26PM +0200, Jan Kundrát wrote:
> Currently we have quite a lot of "unsupported"/"invalid"/"unmaintained"
> documents for one of these reasons:
> 
> a) Third party article

We "can" fix those, but you don't see any news site "fix" their news items
after a year... they are kept online as a reference. You might want to write
a new article about the same subject but more accurate - having the old
article at your disposal can be very interesting.

> b) Older Handbook

Although I can see why you want the chapters of the older handbooks "marked"
as out-dated, some people still use the older handbooks, especially if they
have older release media and want a networkless installation.

But then again, that's not the point :) Personally, I don't think we need
anything red on those handbooks - I would refer to the people's common sense
when they are reading the 2004.3 handbook :)

> c) Translation in language which is not officially supported

We don't link that language; the documents are made available if you know
the URI (which is of course not difficult to grasp). Perhaps we can disable
viewing it entirely unless some variable is set (?override=1) but I don't
think we should.

Each document on our web site is "official" in the sense that either we or a
different Gentoo project is in charge of it. For our documents, this means
that users can post bugreports on the document if they want or even send us
fixes.

With this in mind, having the outdated documents online keeps the bug report
flow coming in - which is a good thing. It has happened in the past that a
guide that was once unmaintained and outdated got updated and is now
accurate and a pleasure to read.

Yes, I know you want something to tell the users "Beware, this document
might contain wrong information" but then again, how would you know the
document gives wrong directives to the user? An old hardware-related guide
might still be perfectly valid - just not updated. Or a very recent guide
can contain erroneous commands while it is still actively maintained.

Imo, as long as there is no AI that can inform us about the malicious
content of a document, we can't easily mark such documents as "outdated" or
"erroneous". I have made a small attempt by allowing us to mark a specific
bug as a showstopper in metadoc - as a result, the document will be unlinked
from the index page. This can be extended by adding-in a <warn> on top of
the document, but you'll have to fight Xavier with this as this results in
another few queries of metadoc and such and makes the XSL again more
obscure.

Wkr,
      Sven Vermeulen




-- 
  Gentoo Foundation Trustee          |  http://foundation.gentoo.org
  Gentoo Documentation Project Lead  |  http://www.gentoo.org/proj/en/gdp
  Gentoo Council Member  

  The Gentoo Project   <<< http://www.gentoo.org >>>

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

Re: [gentoo-doc] [RFC] Marking unmaintained documents

[Jan Kundrát]

[-- Attachment #1: Type: text/plain, Size: 2661 bytes --]

Sven Vermeulen wrote:
>>a) Third party article
> 
> 
> We "can" fix those, but you don't see any news site "fix" their news items
> after a year... they are kept online as a reference. You might want to write
> a new article about the same subject but more accurate - having the old
> article at your disposal can be very interesting.

Well, I'm not talking about fixing, but marking *third-party* articles
as such.

> Although I can see why you want the chapters of the older handbooks "marked"
> as out-dated, some people still use the older handbooks, especially if they
> have older release media and want a networkless installation.
> 
> But then again, that's not the point :) Personally, I don't think we need
> anything red on those handbooks - I would refer to the people's common sense
> when they are reading the 2004.3 handbook :)

Okay, you've persuaded me :-).

>>c) Translation in language which is not officially supported
> 
> 
> We don't link that language; the documents are made available if you know
> the URI (which is of course not difficult to grasp). Perhaps we can disable
> viewing it entirely unless some variable is set (?override=1) but I don't
> think we should.

Neither do I. And yes, you (well, actually someone else, probably rane
or flammie) are right, additional warning might scare users so they
won't trust the translation which is very bad for the first stage of the
process.

> Yes, I know you want something to tell the users "Beware, this document
> might contain wrong information" but then again, how would you know the
> document gives wrong directives to the user? An old hardware-related guide
> might still be perfectly valid - just not updated. Or a very recent guide
> can contain erroneous commands while it is still actively maintained.

I haven't said old document is wrong document, of course not. I was
inspired by some bugreports touching articles.

> Imo, as long as there is no AI that can inform us about the malicious
> content of a document, we can't easily mark such documents as "outdated" or
> "erroneous". I have made a small attempt by allowing us to mark a specific
> bug as a showstopper in metadoc - as a result, the document will be unlinked
> from the index page. This can be extended by adding-in a <warn> on top of
> the document, but you'll have to fight Xavier with this as this results in
> another few queries of metadoc and such and makes the XSL again more
> obscure.

Yep, the question is if it is worth the effort. I'm inclining to say
"no", based on the arguments I've received (except for third-party
articles :-) ).

Cheers,
-jkt


-- 
cd /local/pub && more beer > /dev/mouth

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 256 bytes --]

Re: [gentoo-doc] [RFC] Marking unmaintained documents

[Xavier Neys]

Jan Kundrát wrote:
> Hi GDP-related entities,
> as promised on IRC, here are my ideas about $SUBJECT.
> 
> Currently we have quite a lot of "unsupported"/"invalid"/"unmaintained"
> documents for one of these reasons:
> 
> a) Third party article
> b) Older Handbook
> c) Translation in language which is not officially supported
> d) Outdated translation

Outdated translations are something different, but more about that later.

Adding a disclaimer at the beginning of a doc is a good idea IMO.

To clear a few points:
Adding a disclaimer is not about about making a doc unofficial.
Everything that we publish is official, or has been so at least.
If we want to make a doc officially unofficial, we remove it.

Of course, users reading a 2004.3 handbook should realise it's old, but they 
could at least be told it's not maintained anymore so that 1) they can read it 
with a grain of salt 2) they should not bother submitting bugs.

Dumping the text in the doc itself is not a great idea as it will lead to 
cut'n'paste errors and lose consistency. Besides, scripts could not 
distinguish normal content from such disclaimers.

Another way would have been to list the outdated/unmaintained docs in an 
external file, or add attributes to metadoc. IMO, this adds some unnecessary 
complexity.

I much prefer something along Flammie's idea, a new tag. This way, we just 
need to add the tag to the relevant doc and forget about it.

As we already see the need for different disclaimers, I suggest using a 
<disclaimer> tag with a type attribute. The relevant text is fished from our 
inserts.xml files and I suggest displaying it right at the top of the content 
area. It needs to be either before, after or on the side, but I'd rather not 
insert it randomly in the text.

I have implemented a proposal with the following disclaimers:
"articles" for republished articles
"oldbook" self-explanatory
"obsolete" idem
Disclaimers can also auto-redirect users, very useful for obsolete docs.

Samples:
http://gentoo.neysx.org/mystuff/gentoo-x86-install.xml
http://gentoo.neysx.org/mystuff/l-sed2.xml
http://gentoo.neysx.org/mystuff/l-sed1.xml
http://gentoo.neysx.org/mystuff/oldbook.xml


Now about outdated translations:
It's possible to use metadoc to check the corresponding original and display a 
note about a more recent original.
I've implemented the following:
If a translation is not listed in its local metadoc, warn users translation is 
not maintained.
If a translation is listed in its local metadoc, but not in the parent one 
(ie. the English one), warn users original doc is not maintained anymore.
If file appears both in local and English metadocs, compare their dates and 
warn users that a more recent original exists with a link to it.

Notes:
0) All languages must have a metadoc.xml. Not a problem IMO. <metadoc/> will 
do for currently unsupported languages.
1) We have to use metadoc and *may not* test the corresponding file (ie. 
s:/pl/:/en/:) as that would force us to keep files we want to remove in 
/doc/en/ until all translated versions have disappeared.
2) We need to use the dates and not the versions because using the versions 
would force us to compare handbooks file by file.
3) Reminder: the date of a handbook is the max_date(master, all parts)
4) Some of you need to stop bumping dates needlessly
5) link attributes must contain the full path, no more <book 
link="handbook-x86.xml"> (not required on my test site, but would be on www.g.o)

At the moment, it is limited to /doc as dates are not reliable outside of /doc 
anyway (not yyyy-mm-dd formatted or not bumped properly).

Samples:
http://gentoo.neysx.org/doc/fr/handbook/2005.1/
http://gentoo.neysx.org/doc/pl/nvidia-guide.xml

FYI, an inserts would like like
http://gentoo.neysx.org/doc/en/inserts-en.xml?passthru=1

Please comment.


Cheers,
-- 
/  Xavier Neys
\_ Gentoo Documentation Project
/  French & Internationalisation Lead
\  http://www.gentoo.org/doc/en
/\


-- 
gentoo-doc@gentoo.org mailing list

[gentoo-doc] Re: [RFC] Marking unmaintained documents

[Xavier Neys]

Jan Kundrát wrote:
> Hi GDP-related entities,
> as promised on IRC, here are my ideas about $SUBJECT.
> 
> Currently we have quite a lot of "unsupported"/"invalid"/"unmaintained"
> documents for one of these reasons:
> 
> a) Third party article
> b) Older Handbook
> c) Translation in language which is not officially supported
> d) Outdated translation

Outdated translations are something different, but more about that later.

Adding a disclaimer at the beginning of a doc is a good idea IMO.

To clear a few points:
Adding a disclaimer is not about about making a doc unofficial.
Everything that we publish is official, or has been so at least.
If we want to make a doc officially unofficial, we remove it.

Of course, users reading a 2004.3 handbook should realise it's old, but they
could at least be told it's not maintained anymore so that 1) they can read it
with a grain of salt 2) they should not bother submitting bugs.

Dumping the text in the doc itself is not a great idea as it will lead to
cut'n'paste errors and lose consistency. Besides, scripts could not distinguish
normal content from such disclaimers.

Another way would have been to list the outdated/unmaintained docs in an
external file, or add attributes to metadoc. IMO, this adds some unnecessary
complexity.

I much prefer something along Flammie's idea, a new tag. This way, we just need
to add the tag to the relevant doc and forget about it.

As we already see the need for different disclaimers, I suggest using a
<disclaimer> tag with a type attribute. The relevant text is fished from our
inserts.xml files and I suggest displaying it right at the top of the content
area. It needs to be either before, after or on the side, but I'd rather not
insert it randomly in the text.

I have implemented a proposal with the following disclaimers:
"articles" for republished articles
"oldbook" self-explanatory
"obsolete" idem
Disclaimers can also auto-redirect users, very useful for obsolete docs.

Samples:
http://gentoo.neysx.org/mystuff/gentoo-x86-install.xml
http://gentoo.neysx.org/mystuff/l-sed2.xml
http://gentoo.neysx.org/mystuff/l-sed1.xml
http://gentoo.neysx.org/mystuff/oldbook.xml


Now about outdated translations:
It's possible to use metadoc to check the corresponding original and display a
note about a more recent original.
I've implemented the following:
If a translation is not listed in its local metadoc, warn users translation is
not maintained.
If a translation is listed in its local metadoc, but not in the parent one (ie.
the English one), warn users original doc is not maintained anymore.
If file appears both in local and English metadocs, compare their dates and warn
users that a more recent original exists with a link to it.

Notes:
0) All languages must have a metadoc.xml. Not a problem IMO. <metadoc/> will do
for currently unsupported languages.
1) We have to use metadoc and *may not* test the corresponding file (ie.
s:/pl/:/en/:) as that would force us to keep files we want to remove in /doc/en/
until all translated versions have disappeared.
2) We need to use the dates and not the versions because using the versions
would force us to compare handbooks file by file.
3) Reminder: the date of a handbook is the max_date(master, all parts)
4) Some of you need to stop bumping dates needlessly
5) link attributes must contain the full path, no more <book
link="handbook-x86.xml"> (not required on my test site, but would be on www.g.o)

At the moment, it is limited to /doc as dates are not reliable outside of /doc
anyway (not yyyy-mm-dd formatted or not bumped properly).

Samples:
http://gentoo.neysx.org/doc/fr/handbook/2005.1/
http://gentoo.neysx.org/doc/pl/nvidia-guide.xml

FYI, an inserts would like like
http://gentoo.neysx.org/doc/en/inserts-en.xml?passthru=1

Please comment.


Cheers,
-- 
/  Xavier Neys
\_ Gentoo Documentation Project
/  French & Internationalisation Lead
\  http://www.gentoo.org/doc/en
/\


-- 
gentoo-doc@gentoo.org mailing list

Re: [gentoo-doc] Re: [RFC] Marking unmaintained documents

[Jan Kundrát]

[-- Attachment #1: Type: text/plain, Size: 2073 bytes --]

Xavier Neys wrote:
> Of course, users reading a 2004.3 handbook should realise it's old, but they
> could at least be told it's not maintained anymore so that 1) they can read it
> with a grain of salt 2) they should not bother submitting bugs.

IMHO that's against what SwifT said about fixing?

> Dumping the text in the doc itself is not a great idea as it will lead to
> cut'n'paste errors and lose consistency. Besides, scripts could not distinguish
> normal content from such disclaimers.

Yep.

> Another way would have been to list the outdated/unmaintained docs in an
> external file, or add attributes to metadoc. IMO, this adds some unnecessary
> complexity.

External file would look mroe elegant to me, but that's just me.

> I much prefer something along Flammie's idea, a new tag. This way, we just need
> to add the tag to the relevant doc and forget about it.
> 
> As we already see the need for different disclaimers, I suggest using a
> <disclaimer> tag with a type attribute. The relevant text is fished from our
> inserts.xml files and I suggest displaying it right at the top of the content
> area. It needs to be either before, after or on the side, but I'd rather not
> insert it randomly in the text.

Seems great.

> Now about outdated translations:
> It's possible to use metadoc to check the corresponding original and display a
> note about a more recent original.

That would be great.

> I've implemented the following:
> If a translation is not listed in its local metadoc, warn users translation is
> not maintained.
> If a translation is listed in its local metadoc, but not in the parent one (ie.
> the English one), warn users original doc is not maintained anymore.
> If file appears both in local and English metadocs, compare their dates and warn
> users that a more recent original exists with a link to it.

Well, as I said on IRC, I'd prefer checking <version>, but <date> is
also better than nothing, yep (code which would check <version>s of HB
files is not available).

Cheers,
-jkt

-- 
cd /local/pub && more beer > /dev/mouth

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 256 bytes --]

Re: [gentoo-doc] Re: [RFC] Marking unmaintained documents

[Sven Vermeulen]

[-- Attachment #1: Type: text/plain, Size: 905 bytes --]

On Fri, Sep 16, 2005 at 03:01:04PM +0200, Jan Kundrát wrote:
> Xavier Neys wrote:
> > Of course, users reading a 2004.3 handbook should realise it's old, but they
> > could at least be told it's not maintained anymore so that 1) they can read it
> > with a grain of salt 2) they should not bother submitting bugs.
> 
> IMHO that's against what SwifT said about fixing?

No, because we have an updated handbook (namely the 2005.3/current one). 
Unlike with articles of which we don't have an updated one, any bugreports
against outdated handbooks can be marked as WORKSFORME/INVALID because it is
fixed in the more recent ones.

Wkr,
      Sven Vermeulen

-- 
  Gentoo Foundation Trustee          |  http://foundation.gentoo.org
  Gentoo Documentation Project Lead  |  http://www.gentoo.org/proj/en/gdp
  Gentoo Council Member  

  The Gentoo Project   <<< http://www.gentoo.org >>>

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

Re: [gentoo-doc] Re: [RFC] Marking unmaintained documents

[Alexey Chumakov]

Xavier Neys пишет:
> Notes:
> 0) All languages must have a metadoc.xml. Not a problem IMO. <metadoc/> will do
> for currently unsupported languages.
> 1) We have to use metadoc and *may not* test the corresponding file (ie.
> s:/pl/:/en/:) as that would force us to keep files we want to remove in /doc/en/
> until all translated versions have disappeared.
> 2) We need to use the dates and not the versions because using the versions
> would force us to compare handbooks file by file.
> 3) Reminder: the date of a handbook is the max_date(master, all parts)
> 4) Some of you need to stop bumping dates needlessly
> 5) link attributes must contain the full path, no more <book
> link="handbook-x86.xml"> (not required on my test site, but would be on www.g.o)
> 
> At the moment, it is limited to /doc as dates are not reliable outside of /doc
> anyway (not yyyy-mm-dd formatted or not bumped properly).
> 
> Samples:
> http://gentoo.neysx.org/doc/fr/handbook/2005.1/
> http://gentoo.neysx.org/doc/pl/nvidia-guide.xml
> 
> FYI, an inserts would like like
> http://gentoo.neysx.org/doc/en/inserts-en.xml?passthru=1
> 
> Please comment.
> 
As for me, it's good that we only give a hint -- it's up to our user to
decide if the doc is really obsolete.
Great solution Xavier!

WKR,
Alexey Chumakov

-- 
gentoo-doc@gentoo.org mailing list

Re: [gentoo-doc] [RFC] Marking unmaintained documents

[Xavier Neys]

*This is not a double post even though it might look like one, please read on*

Jan Kundrát wrote:
 > Hi GDP-related entities,
 > as promised on IRC, here are my ideas about $SUBJECT.
 >
 > Currently we have quite a lot of "unsupported"/"invalid"/"unmaintained"
 > documents for one of these reasons:
 >
 > a) Third party article
 > b) Older Handbook
 > c) Translation in language which is not officially supported
 > d) Outdated translation


Outdated translations are something different, but more about that later.

Adding a disclaimer at the beginning of a doc is a good idea IMO.

To clear a few points:
Adding a disclaimer is not about about making a doc unofficial.
Everything that we publish is official, or has been so at least.
If we want to make a doc officially unofficial, we remove it.

Of course, users reading a 2004.3 handbook should realise it's old, but they 
could at least be told it's not maintained anymore so that 1) they can read it 
with a grain of salt 2) they should not bother submitting bugs.

Dumping the text in the doc itself is not a great idea as it will lead to 
cut'n'paste errors and lose consistency. Besides, scripts could not 
distinguish normal content from such disclaimers.

Another way would have been to list the outdated/unmaintained docs in an 
external file, or add attributes to metadoc. IMO, this adds some unnecessary 
complexity.

I much prefer something along Flammie's idea, a new tag. This way, we just 
need to add the tag to the relevant doc and forget about it.

As we already see the need for different disclaimers, I suggest using a 
<disclaimer> tag with a type attribute. The relevant text is fished from our 
inserts.xml files and I suggest displaying it right at the top of the content 
area. It needs to be either before, after or on the side, but I'd rather not 
insert it randomly in the text.
It does not need to be red. Text surrounded by a simple dark blue border might 
just do.

I have implemented a proposal with the following disclaimers:
"articles" for republished articles
"oldbook" self-explanatory
"obsolete" idem
Disclaimers can also auto-redirect users, very useful for obsolete docs.

Samples:
http://gentoo.neysx.org/mystuff/gentoo-x86-install.xml
http://gentoo.neysx.org/mystuff/l-sed2.xml
http://gentoo.neysx.org/mystuff/l-sed1.xml
http://gentoo.neysx.org/mystuff/oldbook.xml


Now about outdated translations:
It's possible to use metadoc to check the corresponding original and display a 
note about a more recent original.
I've implemented the following:
If a translation is not listed in its local metadoc, warn users translation is 
not maintained.
If a translation is listed in its local metadoc, but not in the parent one 
(ie. the English one), warn users original doc is not maintained anymore.
If file appears both in local and English metadocs, compare their versions and 
warn users that a more recent original exists with a link to it.

Some doc dev complained that comparing the dates would not work if two updates 
occurred in the same day. True. Comparing the versions is a bit more complex 
and involves two extra scans of the handbooks (the original and the translated 
one). It's fast enough IMO. My <300Mhz test box still delivers handbook 
chapters under the second. Note that it is still not 100% fool-proof. If a 
chapter disappears from the original, the mention of a more recent original 
would not appear on the translations because the xsl scans the original and 
compares the version with the version of the file that is included at the same 
position (part/chapter-wise) in the translation. That has not happened yet.

I'm not going to parse the version strings to try to quantify the amount of 
changes that occurred because 1) versions are not structured 2) a single bump 
could mean a small or a big change, and vice-versa for more bumps. Displaying 
the date of the original should be a good indication.

Notes:
0) All languages must have a metadoc.xml. Not a problem IMO. <metadoc/> will 
do for currently unsupported languages.
1) We have to use metadoc and *may not* test the corresponding file (ie. 
s:/pl/:/en/:) as that would force us to keep files we want to remove in 
/doc/en/ until all translated versions have disappeared.
2) Reminder: the date of a handbook is the max_date(master, all parts)
3) Some of you need to stop bumping dates needlessly because it would make 
translations look older then they actually are.
4) link attributes must contain the full path, no more <book 
link="handbook-x86.xml"> (not required on my test site, but would be on www.g.o)

At the moment, it is limited to /doc as dates are not reliable outside of /doc 
anyway (not yyyy-mm-dd formatted or not bumped properly).

Samples:
http://gentoo.neysx.org/doc/fr/handbook/2005.1/handbook-amd64.xml?part=1&chap=2
http://gentoo.neysx.org/doc/pl/nvidia-guide.xml

FYI, an inserts would like like
http://gentoo.neysx.org/doc/en/inserts-en.xml?passthru=1

Please comment.


Cheers,
-- 
/  Xavier Neys
\_ Gentoo Documentation Project
/  French & Internationalisation Lead
\  http://www.gentoo.org/doc/en
/\


-- 
gentoo-doc@gentoo.org mailing list

Re: [gentoo-doc] [RFC] Marking unmaintained documents

[Jan Kundrát]

[-- Attachment #1: Type: text/plain, Size: 1288 bytes --]

Xavier Neys wrote:
> Some doc dev complained that comparing the dates would not work if two
> updates occurred in the same day. True. Comparing the versions is a bit
> more complex and involves two extra scans of the handbooks (the original
> and the translated one). It's fast enough IMO. My <300Mhz test box still
> delivers handbook chapters under the second. Note that it is still not
> 100% fool-proof. If a chapter disappears from the original, the mention
> of a more recent original would not appear on the translations because
> the xsl scans the original and compares the version with the version of
> the file that is included at the same position (part/chapter-wise) in
> the translation. That has not happened yet.
> 
> I'm not going to parse the version strings to try to quantify the amount
> of changes that occurred because 1) versions are not structured 2) a
> single bump could mean a small or a big change, and vice-versa for more
> bumps. Displaying the date of the original should be a good indication.

Thanks, I like this idea. Am I correct when I assume that it will check
both handbook-$ARCH.xml and hb-$foo-$bar.xml when displaying only one
chapter and all files for current $ARCH when doing ?full=1 ?

Cheers,
-jkt

-- 
cd /local/pub && more beer > /dev/mouth

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 256 bytes --]

Re: [gentoo-doc] [RFC] Marking unmaintained documents

[Xavier Neys]

Jan Kundrát wrote:
> Xavier Neys wrote:
> 
>>Some doc dev complained that comparing the dates would not work if two
>>updates occurred in the same day. True. Comparing the versions is a bit
>>more complex and involves two extra scans of the handbooks (the original
>>and the translated one). It's fast enough IMO. My <300Mhz test box still
>>delivers handbook chapters under the second. Note that it is still not
>>100% fool-proof. If a chapter disappears from the original, the mention
>>of a more recent original would not appear on the translations because
>>the xsl scans the original and compares the version with the version of
>>the file that is included at the same position (part/chapter-wise) in
>>the translation. That has not happened yet.
>>
>>I'm not going to parse the version strings to try to quantify the amount
>>of changes that occurred because 1) versions are not structured 2) a
>>single bump could mean a small or a big change, and vice-versa for more
>>bumps. Displaying the date of the original should be a good indication.
> 
> 
> Thanks, I like this idea. Am I correct when I assume that it will check
> both handbook-$ARCH.xml and hb-$foo-$bar.xml when displaying only one
> chapter and all files for current $ARCH when doing ?full=1 ?

Almost.
Full handbook: all files are checked
TOC (part and/or chap = 0), master file is checked
Chapter, hb-$foo-$bar.xml is checked, checking the master files as well would 
be trivial, but why should they be checked?


Cheers,
-- 
/  Xavier Neys
\_ Gentoo Documentation Project
/  French & Internationalisation Lead
\  http://www.gentoo.org/doc/en
/\


-- 
gentoo-doc@gentoo.org mailing list

Re: [gentoo-doc] [RFC] Marking unmaintained documents

[Jan Kundrát]

[-- Attachment #1: Type: text/plain, Size: 303 bytes --]

Xavier Neys wrote:
> Chapter, hb-$foo-$bar.xml is checked, checking the master files as well
> would be trivial, but why should they be checked?

Because the section which is displayed might be no longer referenced
(yep, purely hypotetically).

Cheers,
-jkt

-- 
cd /local/pub && more beer > /dev/mouth

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 256 bytes --]

Re: [gentoo-doc] [RFC] Marking unmaintained documents

[Xavier Neys]

Xavier Neys wrote:

> Adding a disclaimer at the beginning of a doc is a good idea IMO.
> 
> I have implemented a proposal with the following disclaimers:
> "articles" for republished articles
> "oldbook" self-explanatory
> "obsolete" idem
> Disclaimers can also auto-redirect users, very useful for obsolete docs.

I have added "draft" and used attributes (disclaimer & redirect) instead of 
yet another element. It feels better(tm) to me.

> Samples:
> http://gentoo.neysx.org/mystuff/gentoo-x86-install.xml
> http://gentoo.neysx.org/mystuff/l-sed2.xml
> http://gentoo.neysx.org/mystuff/l-sed1.xml
> http://gentoo.neysx.org/mystuff/oldbook.xml
http://gentoo.neysx.org/mystuff/pocketpc-guide.xml


> Now about outdated translations:
Reminder:
> 0) All languages must have a metadoc.xml. Not a problem IMO. <metadoc/> 
> will do for currently unsupported languages.
> 1) We have to use metadoc and *may not* test the corresponding file (ie. 
> s:/pl/:/en/:) as that would force us to keep files we want to remove in 
> /doc/en/ until all translated versions have disappeared.
> 2) Reminder: the date of a handbook is the max_date(master, all parts)
> 3) Some of you need to stop bumping dates needlessly because it would 
> make translations look older then they actually are.
> 4) link attributes must contain the full path, no more <book 
> link="handbook-x86.xml"> (not required on my test site, but would be on 
> www.g.o)

> At the moment, it is limited to /doc as dates are not reliable outside 
> of /doc anyway (not yyyy-mm-dd formatted or not bumped properly).

Sample:
http://gentoo.neysx.org/doc/fr/distcc.xml
> 
> FYI, an inserts would like like
> http://gentoo.neysx.org/doc/en/inserts-en.xml?passthru=1


Disclaimer & redirect
   () Yea  () Nay

Note about more recent English version
   () Yea  () Nay


Cheers,
-- 
/  Xavier Neys
\_ Gentoo Documentation Project
/  French & Internationalisation Lead
\  http://www.gentoo.org/doc/en
/\
-- 
gentoo-doc@gentoo.org mailing list

Re: [gentoo-doc] [RFC] Marking unmaintained documents

[Alexey Chumakov]

Xavier Neys пишет:

> Disclaimer & redirect
>   () Yea  () Nay

Yeah

> 
> Note about more recent English version
>   () Yea  () Nay
> 
> 
Yeah


WKR,
Alexey Chumakov
-- 
gentoo-doc@gentoo.org mailing list

Re: [gentoo-doc] [RFC] Marking unmaintained documents

[Jose Luis Rivero]

Xavier Neys wrote:

> Disclaimer & redirect
>   () Yea  () Nay
>
Yea.

> Note about more recent English version
>   () Yea  () Nay
>
Yea.

Both seems ok to me.

Regards.

----------------------------------
YosWinK @ gentoo.org
Gentoo Doc Spanish Team
-- 
gentoo-doc@gentoo.org mailing list

Re: [gentoo-doc] [RFC] Marking unmaintained documents

[Łukasz Damentko]

On Thu, 29 Sep 2005 17:41:06 +0200
Xavier Neys <neysx@gentoo.org> wrote:

> Xavier Neys wrote:

My opinion is known, but, well:

> Disclaimer & redirect
>    () Yea  () Nay

oui

> Note about more recent English version
>    () Yea  () Nay

oui
-- 
gentoo-doc@gentoo.org mailing list

Re: [gentoo-doc] [RFC] Marking unmaintained documents

[Shyam Mani]

[-- Attachment #1: Type: text/plain, Size: 309 bytes --]

Xavier Neys wrote:

> Disclaimer & redirect
(*) Yea  () Nay


> Note about more recent English version
(*) Yea  () Nay

Both of these are good additions. Can we see how the same looks on the
official site btw?

-- 
Shyam Mani | <fox2mike@gentoo.org>
docs-team  | http://gdp.gentoo.org
GPG key    | 0xFDD0E345

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 189 bytes --]

Re: [gentoo-doc] [RFC] Marking unmaintained documents

[Flammie Pirinen]

[-- Attachment #1: Type: text/plain, Size: 901 bytes --]

2005-09-29, Xavier Neys sanoi, jotta:

> Disclaimer & redirect
>    () Yea  () Nay

Nay for delayed redirect. It's confusing and causes only usability
problems. It's also proprietary kludge to HTTP protocol, which has
never been approved to standard for a good reason. Either use instant
redirect with proper HTTP headers or nothing at all. Having automatic
delayed redirect provides nothing useful. If the user misses the
disclaimer and starts reading the document instead he will be very
annoyed and confused when it suddenly disappears, if user sees the
disclaimer he will be perfectly capable of activating the link when he
has finished reading the disclaimer and not any time sooner or later.

> Note about more recent English version
>    () Yea  () Nay

Yay, of course.

-- 
Flammie, Gentoo Linux Documentation's Finnish head translator.
<http://dev.gentoo.org/~flammie>

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

Re: [gentoo-doc] [RFC] Marking unmaintained documents

[Sven Vermeulen]

[-- Attachment #1: Type: text/plain, Size: 597 bytes --]

On Thu, Sep 29, 2005 at 05:41:06PM +0200, Xavier Neys wrote:
> Disclaimer & redirect
>   (*) Yea  () Nay
> 
> Note about more recent English version
>   (*) Yea  () Nay

I do have ears for flammie's points, but I think "timed redirects" are well
supported and used often enough. And they're part of the standard as well :)

Wkr,
      Sven Vermeulen

-- 
  Gentoo Foundation Trustee          |  http://foundation.gentoo.org
  Gentoo Documentation Project Lead  |  http://www.gentoo.org/proj/en/gdp
  Gentoo Council Member  

  The Gentoo Project   <<< http://www.gentoo.org >>>

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

Re: [gentoo-doc] [RFC] Marking unmaintained documents

[Jan Kundrát]

[-- Attachment #1: Type: text/plain, Size: 561 bytes --]

Sven Vermeulen wrote:
> On Thu, Sep 29, 2005 at 05:41:06PM +0200, Xavier Neys wrote:
> 
>>Disclaimer & redirect
>>  (*) Yea  () Nay

disclaimer - yep
redirect - see below, I agree with Flammie, basically

>>
>>Note about more recent English version
>>  (*) Yea  () Nay

yep

> I do have ears for flammie's points, but I think "timed redirects" are well
> supported and used often enough. And they're part of the standard as well :)

I just don't like them, maybe as a relict of old days or whatever...

Cheers,
-jkt

-- 
cd /local/pub && more beer > /dev/mouth

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 256 bytes --]

Re: [gentoo-doc] [RFC] Marking unmaintained documents

[Xavier Neys]

Sven Vermeulen wrote:
> On Thu, Sep 29, 2005 at 05:41:06PM +0200, Xavier Neys wrote:
> 
>>Disclaimer & redirect
>>  (*) Yea  () Nay
>>
>>Note about more recent English version
>>  (*) Yea  () Nay
> 
> I do have ears for flammie's points, but I think "timed redirects" are well
> supported and used often enough. And they're part of the standard as well :)

A/ redirect

My ears heard Flammie as well :)
Delayed redirects are supported and do not even break the back button anymore 
in recent browsers.
Anyway, the redirect attribute is a structured way of saying 'This is doc has 
been replaced by that doc'.
It is *not* a way of turning docs into a slide show or make the handbook jump 
from one chapter to the next.
Now, if users complain about those delayed redirects, we can do several things:
1) if the doc still receives many hits, we can ask infra to add 
rewrite/redirect in the web server config
2) if we had to keep some content in the doc, it's trivial to add a test and 
omit the delayed redirect on docs that contain more than an arbitrary number 
of elements, e.g. more than 1 <section> and 1 <p>
3) we can drop the delayed redirect if it proves really troublesome to our users

I do not expect many hits on those outdated files and the delayed redirect is 
probably the best we can do on www.g.o, but it is not the only way:
http://gentoo.neysx.org/doc/fr/gentoo-x86-install.xml

The redirect attribute is only available in <guide> and should contain the new 
uri.

B/ Disclaimer

A disclaimer attribute can be used on <book> and <guide> tags. Its value can 
be one of (articles|oldbook|draft|obsolete). Inserted text comes from 
inserts-en.xml and is displayed at the top of the content area.

Sample at http://www.gentoo.org/doc/fr/gentoo-x86-install.xml

C/ Note about outdated translations

A note will be displayed under the date when a translation is either not 
maintained or outdated.
This works only if
1) the link attribute has the full path to the doc, not just the file name
2) it starts with /doc/XX/, XX != en

The original to compare to is found using /doc/XX/metadoc.xml which is why 
metadoc has become a requirement for translations.

Sample: http://www.gentoo.org/doc/fr/handbook/handbook-x86.xml?part=1&chap=7

D/ Note about the date and inserts-XX.xml

It has been tricky for some languages to translate 'Updated' to make it work 
by just appending the date.
As translating 'The original version of this document was last updated '+$DATE 
might prove even more difficult, I have added the <docdate/> placeholder in 
inserts.


/me needs to update xml-guide.xml

Cheers,
-- 
/  Xavier Neys
\_ Gentoo Documentation Project
/  French & Internationalisation Lead
\  http://www.gentoo.org/doc/en
/\
-- 
gentoo-doc@gentoo.org mailing list