kicad-developers team mailing list archive

[Nick Østergaard <oe.nick@xxxxxxxxx>]

2015-02-04 15:06 GMT+01:00 Wayne Stambaugh <stambaughw@xxxxxxxxx>:
> On 2/4/2015 7:10 AM, Brian Sidebotham wrote:
>> On 4 February 2015 at 00:14, Wayne Stambaugh <stambaughw@xxxxxxxxx> wrote:
>>> 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 we're pretty much decided already on asciidoc - it just takes
>> someone to say so. I've included Marco on this email so perhaps he
>> could give us his up-to-date conclusion and we can make the decision
>> now.
>>
>> As for being able to build, well, we need to decide on an output
>> format. I think we've previously been hinting at html rather than PDF.
>> We don't need to support a million output formats. PDF is much harder
>> to support compared to HTML for example.

I think HTML and PDF is what is required, I guess some people would
like epub, but that is basically not much different to HTML in
structure, hence I think that should look equally fine in HTML as in
epub.

>> However, nothing requires a POSIX shell, so we definitely don't need
>> to add-in cygwin, MSYS2 or anything else as a dependency for building
>> docs.
>>
>> asciidoc works okay for me under windows, but a2x for PDF conversion
>> doesn't work. However, projects like asciidoctor-fopub and
>> asciidoctor-pdf are well underway to sort that problem out.
>>
>> I'll put a CMake build system in place on the documentation and make
>> sure it works on Windows + Linux. OSX guys will have to help me in
>> making sure it works there. It shouldn't be a problem though.

What does this cmake include? Does it reside in the kicad-doc repo or
in the kicad repo?

>> So decide input and output formats and we can start implementing the
>> CMake build system on the Github repo.
>>
>> Best Regards,
>>
>> Brian.
>>
>
> Brian,
>
> Thank you for stepping up to write the CMake build system.  This is what
> I was looking for.  I didn't want to start down that path without the
> resources in place to get the work done.  I would like to hear from the
> auto builder folks to see what impact it will have on what they are
> doing.  I'll give asciidoc my official blessing (it seems funny to me
> saying that) so we can get moving on it.  The following tasks will need
> to be completed before the stable release:
>
> - Set up repo on some git hosting sight.  I heard some negative feedback
> at FOSDEM about using github since apparently it is not free software so
> I'm open to suggestion on this.  If github is the best choice then I'm
> OK using it but it might be worth exploring other git based hosting
> alternatives.

Ohh well, it is just a git repo, where exactly it is located does not
really matter IMHO. What matters is that pull requests are easy to
perform, but I think it is no fault to put it on github for the
forseeable future at least. We have the "official" libs there anyway,
please don't do any unnessesary fragmentation of the project. By
saying this, I don't want to close the discussion of alternative
places. One is hosting it together with kicad-pcb.org if ajo want to
support and help maintain that.

> - Convert all the existing documentation to asciidoc format.  This
> includes any manual fixes due to incorrect translation.  At some point I
> would also like to see the image file names changes to something
> meaningful rather than 10000000000000400000001FB5B88EB2.png.  This can
> be done as images are changed.

I see Marco have done that with a few of the images.

> - CMake configuration to check for all build dependencies, build all
> required output types, and handle translations.  We will most likely
> have to support PDF output for the next release.  I don't know if html
> help is supported in kicad.  If it is, I'm open to the possibility of
> using html help instead of pdf.

Even if PDF is used "inside" kicad, HTML is still nice when linking
sections to people online.

> Once the initial translation is complete and the repo is set up so
> people can submit patches, I will make an announcement that the official
> documentation has moved and see if I can configure the existing repo on
> launchpad as read only so no one can commit changes.

Well, the repo is already set up by Marco on github,
https://github.com/ciampix/kicad-doc.  Although it might be better
under the KiCad organisation.

> Cheers,
>
> Wayne