1306011 - Prepare the docs to land in mozilla-central

Status: RESOLVED FIXED

(L20n :: General, defect)

Description

[Staś Małolepszy :stas]

Let's clean up the current docs in larch which are mostly about compare-locales and create a new index.rst for the Localization chapter which includes TOC links to compare-locales, glossary, how to use l20n in firefox front-end and the syntax guide.

It will be helpful to build the docs locally to make sure everything looks right:

    https://gecko.readthedocs.io/en/latest/#managing-documentation

Comment 1

[Staś Małolepszy :stas]

Attachment: Bug 1306011 - Document L20n.

Create a new top-level directory l10n/ for the cross-module documentation about
the localization infrastructure and process.

Review commit: https://reviewboard.mozilla.org/r/90862/diff/#index_header
See other reviews: https://reviewboard.mozilla.org/r/90862/

Comment 2

[Axel Hecht [:Pike]]

Comment on attachment 8807880 [details]
Bug 1306011 - Document L20n.

https://reviewboard.mozilla.org/r/90862/#review90818

There are a few bugs down there, some old, some new.

Generally speaking, I think that's the setup of files here is good.

I'm OK with some of the more heavyweight edits to be done in follow-up bugs on larch, though.

I'd like to give this one more turn around.

PS: Locally, I've been diffing against the docs we have in l20n.js, it might be useful for our own history on larch to make that explicit? Not necessary, though, if I'm the only one looking at it.

::: l10n/docs/index.rst:40
(Diff revision 1)
> +repositories are on https://hg.mozilla.org/l10n-central/.
> +
> +You can search inside our localized files on `Transvision`_ and
> +http://dxr.mozilla.org/l10n-mozilla-aurora/.
> +
> +.. _Transvision: https://github.com/l20n/l20n.js/blob/master/docs/syntax.rst

wrong link

::: l10n/docs/l20n.rst:71
(Diff revision 1)
> +You can group resources under a name with the ``name`` attribute::
> +
> +    <link rel="localization" name="main" href="/browser/about-dialogftl">
> +    <link rel="localization" name="new-tab" href="/browser/new-tab.ftl">
> +
> +If the ``name`` attribute is not defined, ``main`` is assumed.

I think we still need the bundle docs here, and explain what to do in XUL. Also bug 1306595 comment 0.

Should I open new bugs on that?

::: l10n/docs/l20n.rst:177
(Diff revision 1)
> +elements but only modifies their text nodes and their attributes. This makes 
> +it possible to use L20n in conjunction with MVC frameworks.
> +
> +You can learn more about DOM Overlays in the `design document`_.
> +
> +.. _design document: https://github.com/stasm/spec/blob/master/dom-overlays.markdown

I think we should put this somewhere that's not in your user account. Either on the l20n/spec repo, or import that document into gecko.rtd, too.

::: l10n/docs/legacy.rst:8
(Diff revision 1)
> -============
> +=====================
> +
> +This document describes the legacy localization infrastructure used in Gecko
> +before 2016.  Unless it has been ported to L20n, existing code still uses this
> +legacy architecture.  New code should should use the new L20n infrastructure
> +and the FTL file format.  Refer to :doc:`l20n` for more information.

I'd not reference 2016 here in the docs, just go for "prior to L20n".

Some of the content here will need to be merged back into l20n.rst. File locations, l10n.ini. Possibly l10n-merge, too.

Not sure if that's a follow-up bug, though.

Comment 3

[Staś Małolepszy :stas]

Comment on attachment 8807880 [details]
Bug 1306011 - Document L20n.

https://reviewboard.mozilla.org/r/90862/#review90818

Thanks for the review, Pike!

I'll land the small changes I made to the docs in the l20n.js repo, so they will be visible in the history there.  I don't think we need to replay them on larch.

> wrong link

Gah, a copy&paste gone wrong. Thanks.

> I think we still need the bundle docs here, and explain what to do in XUL. Also bug 1306595 comment 0.
> 
> Should I open new bugs on that?

Can you explain what you mean by "the bundle docs"?

> I think we should put this somewhere that's not in your user account. Either on the l20n/spec repo, or import that document into gecko.rtd, too.

I suggested moving this to l20n/spec a week ago in an email thread about the L20n docs, so I'll be happy to do it now.

> I'd not reference 2016 here in the docs, just go for "prior to L20n".
> 
> Some of the content here will need to be merged back into l20n.rst. File locations, l10n.ini. Possibly l10n-merge, too.
> 
> Not sure if that's a follow-up bug, though.

I think I'd prefer to ask you to make these edits as you know the legacy system the best.  For this reason, it might be easier to do it in a new bug, or as a new patch here.

Comment 4

[Axel Hecht [:Pike]]

(In reply to Staś Małolepszy :stas from comment #3)
> Comment on attachment 8807880 [details]
> Bug 1306011 - Document L20n.
> 
> https://reviewboard.mozilla.org/r/90862/#review90818
> 
> Thanks for the review, Pike!
> 
> I'll land the small changes I made to the docs in the l20n.js repo, so they
> will be visible in the history there.  I don't think we need to replay them
> on larch.
> 
> > wrong link
> 
> Gah, a copy&paste gone wrong. Thanks.
> 
> > I think we still need the bundle docs here, and explain what to do in XUL. Also bug 1306595 comment 0.
> > 
> > Should I open new bugs on that?
> 
> Can you explain what you mean by "the bundle docs"?

from https://github.com/l20n/l20n.js/blob/master/docs/gecko.rst:

> You can group resources under a name with the name attribute:
> 
> <link rel="localization" name="main" href="/browser/about-dialogftl">
> <link rel="localization" name="new-tab" href="/browser/new-tab.ftl">
>
> If the name attribute is not defined, main is assumed.

That's kinda "why would I want to do that?"

> > I think we should put this somewhere that's not in your user account. Either on the l20n/spec repo, or import that document into gecko.rtd, too.
> 
> I suggested moving this to l20n/spec a week ago in an email thread about the
> L20n docs, so I'll be happy to do it now.
> 
> > I'd not reference 2016 here in the docs, just go for "prior to L20n".
> > 
> > Some of the content here will need to be merged back into l20n.rst. File locations, l10n.ini. Possibly l10n-merge, too.
> > 
> > Not sure if that's a follow-up bug, though.
> 
> I think I'd prefer to ask you to make these edits as you know the legacy
> system the best.  For this reason, it might be easier to do it in a new bug,
> or as a new patch here.

Let's put that into a new bug.

Comment 5

[Staś Małolepszy :stas]

Comment on attachment 8807880 [details]
Bug 1306011 - Document L20n.

Review request updated; see interdiff: https://reviewboard.mozilla.org/r/90862/diff/1-2/

Comment 6

[Staś Małolepszy :stas]

Attachment: Pull request against l20n.js

Comment 7

[Axel Hecht [:Pike]]

Comment on attachment 8807880 [details]
Bug 1306011 - Document L20n.

https://reviewboard.mozilla.org/r/90862/#review91542

r=me, thanks.

Comment 8

[Staś Małolepszy :stas]

Landed in l20n.js: https://github.com/l20n/l20n.js/commit/c4c63b3e1dcab92fc80f52b1d2ce02d369e4c6db

Comment 9

[Staś Małolepszy :stas]

https://hg.mozilla.org/projects/larch/rev/3466e6bc9874e5d7e53649d594ab70af9af2e358
Bug 1306011 - Document L20n. r=Pike