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 <[email protected]> >>> wrote: >>>> On 6 October 2014 14:33, Mitch Davis <[email protected]> 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! > _______________________________________________ Mailing list: https://launchpad.net/~kicad-developers Post to : [email protected] Unsubscribe : https://launchpad.net/~kicad-developers More help : https://help.launchpad.net/ListHelp
