kicad-developers team mailing list archive

[Wayne Stambaugh <stambaughw@xxxxxxxxxxx>]

On 10/6/2014 5:09 PM, Marco Ciampa wrote:
> On Mon, Oct 06, 2014 at 12:13:30PM -0400, Wayne Stambaugh wrote:
>> On 10/5/2014 11:26 PM, Mitch Davis wrote:
>>> Hi,
>>>
>>> On Mon, Oct 6, 2014 at 1:46 PM, Blair Bonnett <blair.bonnett@xxxxxxxxx> wrote:
>>>> On 6 October 2014 14:33, Mitch Davis <mjd+launchpad.net@xxxxxxxxx> wrote:
>>>>>
>>>>> Is there a git mirror for lp:~kicad-developers/kicad/doc?
>>>>
>>>> There is now:
>>>>
>>>> https://github.com/blairbonnett-mirrors/kicad-doc
>>>
>>> Thanks very much!
>>>
>>> I just did a git clone.  Under 3 minutes.  I think bzr would still be going...
>>>
>>>> NB it is big (~800 MB) as most of the files are stored in binary form. There
>>>> has been talk about switching to a text-based documentation source.
>>>> Hopefully when this happens a new repository can be started (freezing the
>>>> old one to retain the history) so its much smaller to obtain.
>>>
>>> Sounds good.  I've been following the debate.  +1 for Sphinx and
>>> reStructuredText.
>>
>> Sphinx looks like a reasonable candidate.  It satisfies the criteria of
>> being available on Linux, Windows, and OSX and there is even a link to
>> an odt to Sphinx converter.
> 
> Sphinx looks one of the few complete documentation packages I have tried.
> I onestly I do not like rest and prefer asciidoc instead but I think that
> sphinx is a wonderful piece of code and I have seen that most of the
> people that use rest use it because of sphinx and not viceversa.
> Besides asciidoc is only slightly different and simpler than rest so it 
> is not so crucial choosing rest instead of asciidoc or markdown.
> 
> See: 
> 
> - http://blog.ser1.net/2011/06/restructuredtext-vs-asciidoc.html
> - http://asciidoctor.org/docs/what-is-asciidoc/ (<- this site is written in asciidoc!)
> 
>> I did a quick scan of the documentation and it seems like it provides 
>> all the features we would need to create high quality documentation.  
>> I don't know anything about Sphinx but I do like the fact that is markdown
>> rather than docbook.
> 
> Actually it is not markdown but rest (RE-Structured-texT) but it is just
> the same: a simpler and human readable format (like markdown or asciidoc)
> that could be converted into docbook easily and automatically.
> 
>> I've never found XML to be very readable.
> 
> I agree, not at all. You have to have the assistance of powerful editors
> like emacs or eclipse to be able to be a docbook prolific writer.
> 
>> I'm depending on the experience of others to make this documentation 
>> conversion happen so all other interested parties
>> please step forward with comments so that we can get this moving forward.
> 
> I ask you all to please have the patience to wait just a little more. I
> have successfully and satisfactory converted the cvpcb manual either in
> asciidoc, markdown and rest and tested with various platforms (pandoc,
> asciidoc, asciidoctor, sphinx). BTW I haven't found an easy/satisfactory 
> way to format the source file to obtain a pdf with the kicad logo image 
> in the front cover ... if someone know how to do it I'm all ears...
> 
> I just want to finish experimenting with what I care most: multilanguage
> support. I want to produce multilanguage versions of the manual creating
> various .po gettext files and re-merge those versions into many
> nationalized versions. I want to test it _before_ making the final
> decision about the tool to use.
> 
> Do we have to choose this important tool quickly? I hope not...

No, we do not have to hurry.  I prefer that we take our time and make a
choice that works the best for the project.  I think you are going about
it the right way by testing the various alternatives.  I just don't want
us holding off keeping the current documentation up to date waiting for
the decision on the new format.  I guess that is not an issue as long as
there is a decent converter from odt to whatever format we choose.
Thank you for working on this.

Wayne

> 
> Thanks!
>