kicad-developers team mailing list archive

[Wayne Stambaugh <stambaughw@xxxxxxxxxxx>]

On 11/25/2014 2:41 AM, Marco Ciampa wrote:
> On Mon, Nov 24, 2014 at 07:19:02PM -0500, Wayne Stambaugh wrote:
>> It's been a few weeks and I haven't heard anything so I'll assume
>> everyone who is interested has looked at Marco's evaluation.  The only
>> folks I didn't hear from were the translators.  I would be nice to know
>> what their preferences are with regard to the new format.  I would like
>> to get this moving so the first order of business is to decide on a
>> format. 
> 
> Thanks Wayne for raising this topic, if it was for me I'll be evaluating
> forever...
> 
>> Looking at the different formats, it seems to me that either
>> asciidoc (easiest to read text format) or reStructuredText (full
>> implementation) be the new format.
> 
> Please note that actually it is somehow viceversa: asciidoc is easier to
> read _and_ more complete, almost comparable to docbook as copleteness,
> see table formatting for example (complete in asciidoc and absolutly
> absent in rest)

I must have misread the feature set breakdown in Wikipedia.  If this is
the case and asciidoc's table formatting meet the requirements that JP
mentioned, then the decision to use asciidoc is a no brainer.
> 
>> Given the differences between
>> markdown implementations (which there seems to be quite a few of), I
>> would rather not depend on it since it seems to straddle the fence
>> between asciidoc and rst.
> 
> Well this is one of my fault. I never obtained to get a complete try of a
> markdown test. The thing is that I got stuck into choosing the md
> "flavour" and real life burden too slowed me down. I am dissadisfacted to
> the fact of not have being able to produce almost one single test
> conversion. If you can manage to wait for just another week I can try to
> create one for the purpouse to see at the results. I am resolved to use
> git-hub version just to see how a good english version appear "live"...

Sure, go ahead and see if you can get some better results with markdown.
 The more information we have the better.  It makes me a bit nervous
that there are so many different flavors of markdown.

> 
> The thing that made me not to discard md at all from the "competition" is
> that I've discovered that the documentation tool that we already use is
> oxygen and oxygen already creates md output, so using one format for all
> docs is not at all a bad idea...

I would be hesitant to use the markdown support provided by Doxygen.  It
seems to be a very limited subset of markdown.  I know because I used it
to add the "Stable Release Policy" and "Road Map" sections to the
developers documentation and I wasn't very impressed.  Doxygen is great
for extracting source code documentation but I don't think it's the most
useful tool for creating general purpose documentation.

> 
>> I've personally played around with asciidoc
>> and rst and to be honest I didn't find rst all that bad
> 
> Apart from table formatting and some other "quirks" like not being able
> to produce bold _and_ italics together...
> 
>> once I cleaned
>> up the formatting of the documentation converted from the odt file some
>> I'm currently leaning that way at the moment since it supports almost
>> all of the elements of docbook.
> 
> ok
> 
>> Lets see if we can come to a consensus over the new few weeks.
> 
> Very well, it is time.
> 
> Many thanks!
>