kicad-developers team mailing list archive

[Miguel Ángel Ajo <majopela@xxxxxxxxxx>]

On Wednesday, 4 de February de 2015 at 17:52, Wayne Stambaugh wrote:




> On 2/4/2015 11:13 AM, Nick Østergaard wrote:
> > 2015-02-04 15:06 GMT+01:00 Wayne Stambaugh <stambaughw@xxxxxxxxx (mailto:stambaughw@xxxxxxxxx)>:
> > > On 2/4/2015 7:10 AM, Brian Sidebotham wrote:
> > > > On 4 February 2015 at 00:14, Wayne Stambaugh <stambaughw@xxxxxxxxx (mailto: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?
> >  
>  
>  
> CMake should be used as the build configuration tool which is used to
> verify all of the required tools are installed on the system and
> automatically generate the appropriate Makefiles. CMake files would go
> in the kicad-doc repo and replace the current Makefiles.
>  
> >  
> > > > 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 (http://kicad-pcb.org) if ajo want to
> > support and help maintain that.
> >  
> >  
> >  

Sorry, I missed that part, I really believe externally provided solutions
are going to be more reliable and work better.

I prefer to spend my very little time in doing things for KiCad than handling
software upgrades, backups, etc...

Lately, the website has proven to be more reliable, partly it was unreliable
because of the huge amount of traffic we have, and that confluence
eats a lot of RAM (thanks java..), but it’s not always been like this.



>  
> >  
> >  
> >  
> > > - 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.
> >  
>  
>  
> It would be nice if everything was in one place. That may be a goal for
> the distant future. For now, we have more important issues to worry about.
>  
> >  
> > > Cheers,
> > >  
> > > Wayne
>  
>  
> _______________________________________________
> Mailing list: https://launchpad.net/~kicad-developers
> Post to : kicad-developers@xxxxxxxxxxxxxxxxxxx (mailto:kicad-developers@xxxxxxxxxxxxxxxxxxx)
> Unsubscribe : https://launchpad.net/~kicad-developers
> More help : https://help.launchpad.net/ListHelp
>  
>