kicad-developers team mailing list archive

[Wayne Stambaugh <stambaughw@xxxxxxxxxxx>]

Marco,

Great work on the conversion analysis.  I finally go around to testing
this and I have to say that I prefer the asciidoc format better than the
markdown and rst formats for plain text readability.  I also could not
convert the asciidoc format to pdf using your example.  I always get an
error about dblatex failing even though I have it installed on my Debian
partition.  None of the section headers or table of contents were
converted so there would obviously be some hand work involved.  That's
not a big deal for the cvpcb documentation but for all of the
documentation there is a lot of work to do.  Windows support is iffy.
Even though MSYS2 has an asciidoc package, the optional bits to create
pdfs is missing so that is an issue.

I guess the next steps are:

* Make the final decision on the format.
* Pick a VCS and a host server.  Obvious choices are bzr/launchpad
  and git/github.
* Convert all of the documentation over to asciidoc.
* Write CMake build configuration support to handle dependency
  checking, out building, translation file creation, and installation.
* Create initial repo and let the document fixing begin.

Any volunteers?

Wayne

On 10/21/2014 5:58 PM, Marco Ciampa wrote:
> 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.
>