kicad-developers team mailing list archive

[Dick Hollenbeck <dick@xxxxxxxxxxx>]

On 09/22/2011 09:20 AM, Brian Sidebotham wrote:
> On 22 September 2011 15:02, jp.charras <jp.charras@xxxxxxxxxx> wrote:
>> Le 22/09/2011 14:55, Wayne Stambaugh a écrit :
>>> On 9/22/2011 6:04 AM, fabrizio wrote:
>>>> Hello,
>>>> Now that the new 26pth kicad icons are basically finished (I'll maybe
>>>> send reviews of some of them if necessary) I'd like to bring up the
>>>> topic of documentation.
>>>>
>>>> As far as I understand Kicad has some manuals written in OpenOffice
>>>> and a one step by step tutorial. On top of that there are the
>>>> translations of them, all done in OpenOffice.
>>>>
>>>> Before the new face-lifted kicad gets released, these manuals need to
>>>> be updated and maybe reviewed. this might suggest that we could choose
>>>> a different documentation format for kicad (web-based, online
>>>> wiki-based, html documentation accessible via the kicad menu,
>>>> restructured text, etc.).
>>> How do we get the documents from the wiki into PDF (the format supported
>>> by
>>> Kicad) for the binary distributions that most users will install?  The
>>> user
>>> manuals are currently kept in a separate repo so that documentation
>>> contributors do not need access to the source repo and that some level of
>>> change control is maintained.  This prevents anybody from dumping anything
>>> into
>>> the documentation and allows for changes to easily be rolled back.  I have
>>> no
>>> preference over the format used for generating the documentation.  There
>>> are
>>> plenty of good alternatives available.  I personally will continue to
>>> generate
>>> the file format documentation in ODF format.  If someone wants to
>>> translate it
>>> into some other format, I'm OK with that.
>>>
>>
>> I also will continue to generate the file format documentation in ODF
>> format.
>> For me the pdf files are like binaries for a program,
>> and the odf files are the sources (like the .cpp files).
>> From .odf files other formats (pdf, html ...) are easy to generate.

IMO Open Office (aka Libre Office) is a fine choice.

Recent versions support the fodt file format, which is a "flat odt" file, without the
wrapper zip file.

I've got the new/sweet_spec_for_schematic_parts_EN.fodt file in that format, thinking it
would dove tail with version control better.  But it is a noisy XML format, and diff's are
not human readable, at least not by this one.

Also, it is still a little early for that format, only the most very recent versions of
Open Office are supporting it up adequately. 

Long to middle term however, it may make the most sense for documentation format.  It is
an open office document, plain and simple, just without the wrapping zip container.


Dick