kicad-developers team mailing list archive

[Marco Ciampa <ciampix@xxxxxxxxx>]

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.

Cheers

--


Marco Ciampa

I know a joke about UDP, but you might not get it.

+------------------------+
| GNU/Linux User  #78271 |
| FSFE fellow       #364 |
+------------------------+