kicad-developers team mailing list archive

[Wayne Stambaugh <stambaughw@xxxxxxxxxxx>]

On 9/20/2014 7:36 PM, Marco Ciampa wrote:
> On Sat, Sep 20, 2014 at 02:39:50PM +0200, Kerusey Karyu wrote:
>> All the Polish help docs has been ported/converted to HTML format and
>> committed. Now you have to decide to keep, archive or remove their PDF
>> editions and ODF sources.
> 
> Please, don't for now, be patient.
> 
> I am tryng to convert all ODF docs in a more manageable format.
> The HTML format IMHO should be obtained by automatic compilation like
> other useful formats for the documentation.

I agree with Marco on this.  I don't think HTML is a good native format
for creating documentation.

> 
>> By the way. My friend ask me: "Why don't you use a Compiled HTML Help
>> (CHM) system? I saw a Linux client for that..."
> 
> You correctly said "compiled". If you "compile" something you must have
> somewhere some sort of "source". Using that source you can, easily and in
> a maintainabile manner, manage automatically the format conversion.
> 
> Nowadays, documentation is rarely directly written in HTML.
> Usually docs are created automatically by conversion from
> another more standard and/or manageable format like SGML, XML-DOCBOOK,
> Markdown, Asciidoc, Rest or the like, and then converted automatically
> (and correctly) into HTML, odt, pdf, CHM, rtf, LaTex or even epub.

This is how I prefer to see it done as long as the tools are available
on all platforms supported by kicad.

> 
> And, as a "bonus track" you gain an easy manageable and maintainable
> method  for handling multilanguage doc translations
> 
> With such a method it is straitforward to obtain and update all
> translated docs that are changed in the source reference language and
> format and propagate such changes into all languages sources.
> 
>> As a "bonus track" you can take a look at English KiCad Manager doc
>> using my style sheet.
>> https://github.com/keruseykaryu/kicad-kerusey-doc-html/tree/master/doc/help/en
> 
> That could be reused, so it will not be a waste of time. Likewyse the
> translation sources, with a little bit of effort of cut & paste... but
> please wait because I do not want you to waste time into unneeded
> conversions.
> 
> Many thanks!
>