kicad-doc-devs team mailing list archive

[f.dos.santos@xxxxxxx]

Hi,

I don't know if .po translation files will work well with cherry-picks.

I've been thinking (and testing) an alternative that "could" work : no change for translators and only a small hassle for writer/maintainer.
The idea is to get stable and development text section in the same file and using conditional compilation at build time.

In the .adoc file you put your text for new features in :

   ifdef::DEVELOPMENT_VERSION[]
   ... specific section for development version 
   endif::[]

and for text that apply only to the stable release :

   ifndef::DEVELOPMENT_VERSION[]
   ... specific section for stable version 
   endif::[]

When building the docs we pass a definition variable "DEVELOPMENT_VERSION" based on the git branch/tag, if we are on master we build with the development version on, if not the stable version will be build.

I've tested it and it works as expected :
- the updatepo will put both texts in the po file, 
- text that appear in the documentation depends on the DEVELOPMENT_VERSION variable

So no added work for translators, they should translate as usual.

Writer should add those macros for text added and specific to the development version and never remove the previous text if it's still valid in the stable release.

When the time come for the next major release, those macros should be tracked and removed to finally have identical stable and development version, and the process goes on. 

If you think it's a good idea, I'll push my tests so that you can try it. That something we should all agree upon to make it work.

It's not a perfect solution, it's in no way a substitute for proper version control, but it can be an alternative to full blown branch when in fact our documentation doesn't change that much between stable and development release.


Francisco

----- Mail original -----
From: "Marco Ciampa" <ciampix@xxxxxxxxxx>
To: kicad-doc-devs@xxxxxxxxxxxxxxxxxxx
Date: 06/05/2020 11:59:29
Subject: [Kicad-doc-devs] let's be brave and fork!

This issue:

https://gitlab.com/kicad/services/kicad-doc/-/issues/773

is directly related to our lack of manpower or really to our lack of courage?

Lets fork the docs and purge the 5.* docs from 6.* new features info.

For what I see docs are already frozen and that can be a reason.

Making cherry-picks here and there between the two branches should not be
a big deal...

What do you think?

--

Saluton,
Marco Ciampa

-- 
Mailing list: https://launchpad.net/~kicad-doc-devs
Post to     : kicad-doc-devs@xxxxxxxxxxxxxxxxxxx
Unsubscribe : https://launchpad.net/~kicad-doc-devs
More help   : https://help.launchpad.net/ListHelp