kicad-developers team mailing list archive

[Martijn Kuipers <martijn.kuipers@xxxxxxxxx>]

On 01 Sep 2014, at 19:54, jp charras <jp.charras@xxxxxxxxxx> wrote:

> Le 01/09/2014 11:44, Brian Sidebotham a écrit :
>> On 1 September 2014 10:17, Javier Serrano
>> <javier.serrano.pareja@xxxxxxxxx> wrote:
>>> On Sat, Aug 30, 2014 at 8:47 PM, Wayne Stambaugh <stambaughw@xxxxxxxxxxx> wrote:
>>> [snip]
>>>> I am proposing that we move to a model more like the
>>>> Linux kernel where there is a merge window for new features followed by
>>>> a stabilization period.
>>> [snip]
>>> 
>>> This looks like a very good plan to me. You can count on our help.
>>> 
>>>> 3) Documentation
>>> [snip]
>>>> There has been a suggestion of moving our documentation to a text base
>>>> layout format to make it more version control and translation friendly.
>>>> I'm all for that.
>>> 
>>> How is the current documentation effort being handled? Is there a
>>> separate mailing list for it? I don't recall seeing much documentation
>>> discussion here. What do the main people involved think about changing
>>> to a markup text-based format?
>>> 
>>> Cheers,
>>> 
>>> Javier
>> 
>> Oh, that quickly reminds me - I had started looking at this here:
>> https://github.com/BrianSidebotham/KiCAD-Docs-mmd
>> 
>> I think the problem we need to get around if Markdown is chosen as the
>> markup because of it's simplicity that formatting the size of images
>> is not really present, and this is why it's hard to get a formatted
>> PDF document out correctly. However, we all have browsers these days,
>> perhaps the documentation in html rather than PDF makes more sense
>> anyway.
>> 
>> For HTML of course, we can use CSS to style the output - there's no
>> CSS in the above html output.
>> 
>> Best Regards,
>> 
>> Brian.
> 
> After a lot of try (using Markdown, LibreOffice .fodt files and trying
> to use some other formats), I agree with Brian:
> 
> Using html format for *current Kicad documentation* is the best way:
> * Current doc is very easy to convert to html format (LibreOffice, at
> least the latest version 4.3.1, works fine when switching to html file
> format) from the current .odt format ( we have more than 1000 pages of
> currently actively maintained doc, therefore this is a very important
> thing).
> * No need to still generate the .pdf files, html files are enough.
> * Using html files instead of .odf files, and do not use anymore pdf
> files fixes our major issue: binary files are not easily handled by
> launchpad versioning system).
> * Kicad doc file can be converted to html files with very few changes in
> code (FYI, in early times of Kicad, the html format was used)

I find it much easier to move pdf-files around then html-files. Why not use a solution such as latex, or perhaps less academic, sphinx ?
The cakePHP book is done with sphinx, which is basically restructured text (so you can keep it in a CVS), but can output a myriad of formats, such as html, pdf (via latex), ePub,

There is a tool to convert from odf, but I have not tried it.

For those interested, more info on sphinx can be found here: http://sphinx-doc.org/intro.html

Warm regards,
Martijn

> 
> -- 
> Jean-Pierre CHARRAS
> 
> _______________________________________________
> Mailing list: https://launchpad.net/~kicad-developers
> Post to     : kicad-developers@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~kicad-developers
> More help   : https://help.launchpad.net/ListHelp