kicad-doc-devs team mailing list archive

[Marco Ciampa <ciampix@xxxxxxxxxx>]

On Wed, May 06, 2020 at 01:13:50PM +0200, f.dos.santos@xxxxxxx wrote:
> Hi,
> 
> I don't know if .po translation files will work well with cherry-picks.

I mentioned cherry-picks as an example but there is a way (deleting
comments and sorting messages alfabetically) to merge the .po files
gracily.

> 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.

Well at the very least it is a new (and ingenuous) idea. I have mixed
feelings about that though, I do not really why, perhaps because it is a
sort of a hack...

But I am not against it. I just want to hear other opinions about that...

> 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::[]

have you tested it also with asciidoctor? Because one of these days I
think we will migrate to that (more modern) tool...

> 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.

If the differences between the stable and the dev branches are small,
that could be feasible, but I imagine that the more different the two
branches they become the more painful this method will be...

> 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. 

Well it is certainly a good idea!

> That something we should all agree upon to make it work.

I agree and, lets say I am not agains and not for, let's hear others...
 
> It's not a perfect solution, 

but it is A 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.
> 

Many thanks Francisco!

-- 

Saluton,
Marco Ciampa