kicad-developers team mailing list archive

[jp charras <jp.charras@xxxxxxxxxx>]

Le 25/11/2014 08:41, Marco Ciampa a écrit :
> 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)
> 
>> 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"...
> 
> 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'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...

Table formatting (at least a simple but decent table formatting,
allowing images in tables), bold _and_ italics and small image insertion
(like a char in a string) are widely used in current Kicad doc.

There features must be considered for the final choice.

The leak of table formatting is a serious issue in markdown which has
too poor formatting options.

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


-- 
Jean-Pierre CHARRAS