kicad-developers team mailing list archive

[Brian Sidebotham <brian.sidebotham@xxxxxxxxx>]

Excellent work Marco. Sorry, replying on my phone!

Picking the right tool is essential, we're just itching to make the
transition to text based documentation, that's all. We've had odt
documentation for a long time, and we can suffer that for a while longer
while we evaluate the text based solutions.

Thank-you so much for testing everything out, particularly testing the
internationalization features supported by those functions, it's something
where I have zero experience and I'm sure the translators will be very
happy with an easier to use system!

Thanks again!

Brian.
On 6 Oct 2014 22:09, "Marco Ciampa" <ciampix@xxxxxxxxx> 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...
>
> Thanks!
>
> --
>
>
> Marco Ciampa
>
> I know a joke about UDP, but you might not get it.
>
> +--------------------+
> | Linux User  #78271 |
> | FSFE fellow   #364 |
> +--------------------+
>
>
> _______________________________________________
> Mailing list: https://launchpad.net/~kicad-developers
> Post to     : kicad-developers@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~kicad-developers
> More help   : https://help.launchpad.net/ListHelp
>