kicad-developers team mailing list archive

[Wayne Stambaugh <stambaughw@xxxxxxxxxxx>]

On 10/25/2014 6:17 PM, Marco Ciampa wrote:
> On Sat, Oct 25, 2014 at 10:52:54AM -0400, Wayne Stambaugh wrote:
>> Marco,
>>
>> Great work on the conversion analysis.  I finally go around to testing
>> this and I have to say that I prefer the asciidoc format better than the
>> markdown and rst formats for plain text readability.
> 
> Almost everyone does it but please consider that readability is not the
> most important factor. As I said many people use rest because of sphinx.
> Please consider that sphinx integrate a search javascript function into
> the html generated, although maybe not so important.

My main issue with the rst formatting was the fact that odt2sphinx
creating very long line which in some cases wrap more than once using a
100 character line width editor.  This is a serious problem IMO.
Looking at wrapped lines in a text editor makes my eyes bleed.  I hope
this is just the output formatting issue with odt2sphinx and not
required by the rst format.  Please don't underestimate the importance
of plain text readability.  If I have to struggle to figure out the file
format, I will be less motivated to contribute to maintaining the
documentation. My guess is that other potential contributers will feel
the same way.  That being said, rst would be tolerable if the formatting
issues can be resolved.  Are there features in rst that are not in
asciidoc or markdown that are required to generate the kicad
documentation?  If so, then that tends to tip things in favor of rst.
If not, then the less readable syntax would favor asciidoc.

> 
>> I also could not convert the asciidoc format to pdf using your example.
>> I always get an error about dblatex failing even though I have it 
>> installed on my Debian partition.
> 
> I use Ubuntu 14.04. Maybe Debian asciidoc or dblatex packages are bit
> older?
> 
> 1. Please print the output error strings eventually augmenting verbosity.
> 2. try -L or  --no-xmllint option, to disable xmllint check for sometimes 
> xmmlint is too picky 
> 3. try using asciidoctor to convert into xml first, exec a2x with -n or 
> --dry-run to see the command line it execs to try to do it manually 
> substituting ascidoc with asciidoctor
> 
> TIA
> 
>>  None of the section headers or table of contents were
>> converted so there would obviously be some hand work involved.  That's
>> not a big deal for the cvpcb documentation but for all of the
>> documentation there is a lot of work to do.  Windows support is iffy.
>> Even though MSYS2 has an asciidoc package, the optional bits to create
>> pdfs is missing so that is an issue.
>>
>> I guess the next steps are:
>>
>> * Make the final decision on the format.
> 
> ok
> 
>> * Pick a VCS and a host server.  Obvious choices are bzr/launchpad
>>   and git/github.
> 
> I am for git...
> 
>> * Convert all of the documentation over to asciidoc.
> 
> I can do it... no problem.
> 
>> * Write CMake build configuration support to handle dependency
>>   checking, out building, translation file creation, and installation.
> 
> I do not know cmake at all
> 
>> * Create initial repo and let the document fixing begin.
> 
> ok
> 
>> Any volunteers?
> 
> Count on me of course.
>