Re: [Kicad-developers] New documentation format.
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 ___ Mailing list: https://launchpad.net/~kicad-developers Post to : kicad-developers@lists.launchpad.net Unsubscribe : https://launchpad.net/~kicad-developers More help : https://help.launchpad.net/ListHelp
Re: [Kicad-developers] New documentation format.
Le 25/11/2014 09:34, jp charras a écrit : The leak of table formatting is a serious issue in markdown which has __ Sorry: The lack of table ... too poor formatting options. -- Jean-Pierre CHARRAS ___ Mailing list: https://launchpad.net/~kicad-developers Post to : kicad-developers@lists.launchpad.net Unsubscribe : https://launchpad.net/~kicad-developers More help : https://help.launchpad.net/ListHelp
Re: [Kicad-developers] New documentation format.
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! ___ Mailing list: https://launchpad.net/~kicad-developers Post to : kicad-developers@lists.launchpad.net Unsubscribe : https://launchpad.net/~kicad-developers More help : https://help.launchpad.net/ListHelp
