← Back to team overview

kicad-developers team mailing list archive

Re: on documentation format ...

 

I think Marco mentioned on IRC that you could provide multiple files to
po4a and solve it with the make scripts. Of course this should not hold
anyone back at patching.

Is this correct Marco?
Den 06/02/2015 23.56 skrev "Cirilo Bernardo" <cirilo.bernardo@xxxxxxxxx>:

> On Sat, Feb 7, 2015 at 2:27 AM, Marco Ciampa <ciampix@xxxxxxxxx> wrote:
>
>> Hi all.
>>
>> It seems that it is time to choose a format for good.
>> I am insecure by nature so I am stuck on this quandary: asciidoc or rest?
>>
>> I was almost making up my mind when Alexander Golubev rightly asked me
>> how to split big documents as the pcbnew and eeschema ref manuals into
>> many, one for chapter, files.
>>
>> It turned out that while sphinx is perfectly capable of updating the po
>> files that refers to the multiple splitted chapter files, po4a on which
>> asciidoc relies for i18n, does not "understand" the asciidoc include file
>> macro. This fact means that po4a is not able, by itself, to build a
>> single  big or multiple .po files (one for chapter) files from any
>> asciidoc with include macro by itself (that means without the help of
>> some makefile/script magic). And above all, this means that po4a is not
>> able to update the included files with the correct strings from the
>> correct .po file, again without any external (=scripts) help.
>>
>> So we have to:
>>
>> - get rid of the inclusion of multiple chapter files and collect all
>>   chapters into one single, one for manual, big file for asciidoc.
>>   Simple solution but not very nice.
>>
>> or
>>
>> - try to find a solution via makefile/scripts to obtain one po file per
>>   chapter (may be the best solution) for asciidoc, recreate/updated all
>>   chapter files using the po files like we are doing now with the single
>>   file documents we have now (if you have already a simple solution,
>>   please fork & commit! :-)
>>
>> or
>>
>> - get rid of asciidoc altogether and use sphinx that does not have this
>>   problem. Apart from being slightly simpler & less sophisticated format
>>   it is not a big change from asciidoc. We lose some formatting options
>>   on tables and we gain support from https://readthedocs.org/, very
>>   interesting platform. But if we may be concerned on rely on github for
>>   just the git repo (not a big problem IMHO) maybe this could not a very
>>   wise decision...
>>
>> I am investigating the second option. In the meantime please say what you
>> think about the format to choose.
>>
>>
>>
> What a nuisance that po4a does not recognize "include". Maybe we should
> submit a patch to po4a?  Otherwise my own preference would be to continue
> to use individual text files for chapters and to use other tools to glue
> them
> together before invoking asciidoc. UNIX systems usually have several
> tools installed which can do the job of stringing the files together (even
> most
> shell environments have such built-in facilities). MinGW/MSys would also
> have such facilities.
>
> - Cirilo
>
>
> _______________________________________________
> Mailing list: https://launchpad.net/~kicad-developers
> Post to     : kicad-developers@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~kicad-developers
> More help   : https://help.launchpad.net/ListHelp
>
>

Follow ups

References