kicad-developers team mailing list archive

[Marco Ciampa <ciampix@xxxxxxxxx>]

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...

Thanks!

-- 


Marco Ciampa

I know a joke about UDP, but you might not get it.

+--------------------+
| Linux User  #78271 |
| FSFE fellow   #364 |
+--------------------+