kicad-developers team mailing list archive

[Marco Ciampa <ciampix@xxxxxxxxx>]

Hello,

talking about the project of switching the KiCad documentation to an
easier to maintain and translate format, after some experiments, (I know,
I am slow ... I am not a real programmer) I have produced something
to check.

This is in effect something like an RFC: I need your comments,
suggestions, improvements (and patches are welcome).

I started writing an email, this:

https://github.com/ciampix/kicad-doc/blob/master/doc/kicad-doc-doc.adoc

it got bigger and bigger and it is not finished, but I though that it
could be useful to publish it before being closed because I do not want
to write it all alone.

Along with this text there are two dirs in src: asciidoc and rest.
Basically these folders contain the cvpcb manual converted into asciidoc
and rest and the small example scripts to create docs into html/pdf/epub.

The complete cycle is:

(odt->)asciidoc/rest
->translation extraction
->(translation)
->merge->nationalized pdf/html/epub

The examples are in asciidoc and rest but the asciidoc toolchain is
almost the same for markdown. I have reported some comments about
txt2tags, textile and sisu but I do not have studied these tools enough
to have a clear idea about.

So I ask you to:

 - have a say about the work
 - try my examples
 - express your preferences about:

  a. the documentation text format
  b. the data organization of the manuals, in particular:
   - file name/extension conventions
   - source files folders,
   - image folders
   - makefiles/cmake configuration (I do not know anything about cmake...)
   - any other thing

If you have any doubt or problem about anything please express yourself.

I do not think we are in a hurry so I think that we can our time to
decide and clear out any quandary.

When we will have decided the source text format we will start converting
all the manuals. Please bear in mind that *anything written in a foreign
language that is not strictly adherent to the english reference manual
will have to be removed*.

So, if you think that something you have written in a localized manual is
not present in the reference, try to translate it in English for the
inclusion in the reference: doing this may save your translation and give
a hand to the whole project.

PS: ... and please forgive my terrible English.

-- 


Marco Ciampa

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

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