kicad-developers team mailing list archive

[John Beard <john.j.beard@xxxxxxxxx>]

On Tue, 2015-02-03 at 19:14 -0500, Wayne Stambaugh wrote:
> On 2/3/2015 6:55 PM, Cirilo Bernardo wrote:
> > It has been some time since Marco has done an evaluation of document
> > format alternatives. Has any decision been made yet about what format we
> > shall use, or are there still some other alternatives which are being
> > investigated?
> > 
> > - Cirilo
> > 
> We need to make a decision soon if we want to get the documentation
> conversion completed in time for the next stable release.  I'm still not
> sure we can build on Windows.  Neither the MSYS2 asciidoc or sphinx
> implementations worked correctly the last time I tried them and I have
> no way to test any of this on OSX.  Cygwin may work but the last time I
> tried to build kicad on cygwin, it was more trouble than it was worth.
> This would limit us to building the documentation only on linux which
> I'm not terribly thrilled about.  This means if you wanted to build a
> windows installer you would have to run linux in a VM to build the
> documentation.  That would be painful for our auto builders folks.  If
> we get much further along, we may just have to live with the
> documentation we have now and convert to a plain text format for the
> next release.

I think the availability of tools on those platforms is actually not of
huge significance. The worst case is that the docs are built for every
commit by something like Jenkins, and the binary files are packaged for
the "bad" platforms, as well as put up online (any code or file host
would do) so you don't need to install KiCad to read the docs.

However, I think that it is _extremely_ important to get the docs into a
useful state ASAP. As it stands, they are not really usable because:

   * The initial download is several hundred of MBs (maybe GBs) due to
     the binary compressed data being stored - every change produces a
     whole new (zipped) ODT and PDF. A lightweight checkout is better,
     but you can't commit changes to a Bazaar lightweight checkout 
     (other DVCS may allow it)
   * It's ugly, because it's in office software, and that always ends up
     with sqiffy documents because things get out of line, and so on
   * All the icons and common images are embedded in these binary blobs
     and therefore replicated thousands of times
   * Translation is impossible without rewriting the document from
     scratch, so divergence is inevitable
   * It's un-versionable, even if the ODTs weren't compressed, they are
     still extremely complex XML formats. This means you can't submit a
     change to it easily, all you see is binary diffs, and that's not a
     good way to manage changes, on a mailing list, Launchpad or
     elsewhere!

All the above mean that the docs are falling into disrepair, and the
talk of the new format means no one wants to do anything. I'd love to
write some documentation, but I have to say, in the current state, I
don't even know where to go, let alone want to do it 4 times in 4
formats.

My vote is for asciidoc - it works and it's readable. Marco has done and
is doing a great job of the conversion into three concurrent formats,
but that will all start to go wrong if the originals start to change
underfoot.

The other factor in this decision is that it's not a disaster if a
better option comes up later - asciidoc (and the other new formats) are
all machine-parseable, that's the point. So they are designed to be
convertible. The critical thing is to choose one, ASAP, and get people
using it and work out a workflow that isn't "here's a new version of the
whole file attached to an email, please commit, and no you can't see
what I changed easily".

No format will be perfect, so I think it's more important to get the
bikes out of the rain than discuss the colour of the shed! If we get
focus onto a single format, we are more likely to be able to find a
solution.

As I said the worst case for other platforms is what we have now, with
an online binary depository of documentation that is kept up to date by
others. Github, at least, can parse asciidoc and present it without even
needing to compile[1], and there are also Firefox and Chrome plugins[2]
that are (I think) platform independent. People can still write the
(underlying, English) docs, even if they can't compile to every format.
The translation can also be done without any special software, though
the end result won't be compiled. Still, it's better than tabbing
between two ODTs!

Remember, if no one can contribute, it doesn't matter which platform they
are using to not contribute!

Cheers,

John

[1] https://github.com/ciampix/kicad-doc/blob/master/src/asciidoc/CvPcb/CvPcb.adoc
[2] https://addons.mozilla.org/en-US/firefox/addon/asciidoctorjs-live-preview/