On 2/4/2015 7:10 AM, Brian Sidebotham wrote: > On 4 February 2015 at 00:14, Wayne Stambaugh <stambau...@gmail.com> 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. > > 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. > > 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. - 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. - 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. 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. Cheers, Wayne _______________________________________________ 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
