kicad-developers team mailing list archive

[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