kicad-developers team mailing list archive

[Martijn Kuipers <martijn.kuipers@xxxxxxxxx>]

On 01 Sep 2014, at 21:54, Brian Sidebotham <brian.sidebotham@xxxxxxxxx> wrote:

> On 1 September 2014 20:17, Martijn Kuipers <martijn.kuipers@xxxxxxxxx> wrote:
>> 
>> 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
> 
> I'm unsure why the files need moving around?

It’s easy to have a pdf and put it in my folder with documentation. Even today, I do not always have internet access and it is not so easy to organise docs on a localhost (in my opinion).


> Almost the entire weight of this decision should be in the hands of
> the people who write the documentation. Latex I'm sure is definitely
> out - it's hard to see the content for the formatting, so it's not
> easy to work with. We want to create a situation where documentation
> writers can use text diffs to update their language's documentation.
> 
> So something like restructured text may work well because it has some
> image formatting capabilities.

I concur. If it was some kind of (re)structured text, then it would be easy to send patches and might get more people involved.

> 
> Plain HTML can actually do the job too, although most people use a
> language that compiles to html to make the formatting even cleaner.

Exactly, the example I gave (sphinx) does exactly that and allows to create the handy pdf as well.
> 
> Markdown has books written in it too.

So does Latex, still we can some kind of agree that it is not very friendly to the eyes. In my field there is no real alternative, that handles equations as well as latex does,.

> 
> Best Regards,
> 
> Brian.

Warm regards,
Martijn