kicad-developers team mailing list archive

[jp charras <jp.charras@xxxxxxxxxx>]

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)

-- 
Jean-Pierre CHARRAS