kicad-developers team mailing list archive

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

2015-02-09 12:01 GMT+01:00 Marco Ciampa <ciampix@xxxxxxxxx>:
> On Mon, Feb 09, 2015 at 10:09:04AM +0000, Brian Sidebotham wrote:
>> On 7 February 2015 at 00:09, Marco Ciampa <ciampix@xxxxxxxxx> wrote:
>> > On Sat, Feb 07, 2015 at 09:56:36AM +1100, Cirilo Bernardo wrote:
>> >> What a nuisance that po4a does not recognize "include". Maybe we should
>> >> submit a patch to po4a?
>> >
>> > That would be the best thing to do.
>> >
>> >> Otherwise my own preference would be to continue to use individual text
>> >> files for chapters and to use other tools to glue them together before
>> >> invoking asciidoc.
>> >
>> > I think that that would resolve the problem in the meantime that po4a devs
>> > patch the program.
>> >
>> > That would be the simpler thing to do, but we could have to introduce the
>> > convention of, for example, call the docs with include directive in it
>> > docname-master.adoc to obtain a "fusion" of
>> > docname_master.adoc+docname_chapter_01.adoc+docname_chapter_02.adoc...
>> > into ->docname.adoc
>> >
>> > nevermind... I've already resolved with some makefile+scripting+sed magic
>> > :-) pushing it in a few minutes...
>> >
>> > We just have to follow the convention of calling the chapters
>> >
>> > DOCNAME_chapter_NN.adoc
>> >
>> > etc. as we already do.
>> >
>> >> UNIX systems usually have several tools installed
>> >> which can do the job of stringing the files together (even most shell
>> >> environments have such built-in facilities). MinGW/MSys would also have
>> >> such facilities.
>> >
>> > sed you mean?
>>
>> We definitely won't be using sed,
>
> Why not? Sed is nearly ubiquitous in the Unix environment...
>
>> so don't worry too much about the building of the docs.
>
> I find that building the docs is useful to check the results...
>
>> We don't need sed 'foo' or anything as we have
>> CMake and it can do everything we need *cross platform*.
>
> We already settled for not caring too much for the doc building *cross
> platform* since actually there is no (even using sphinx) tool able to
> build docs *cross platform*. This is due to the fact that the majority of
> the tools use docbook as an intemediate format, that use xml stylesheets
> transformations, latex and other tricks to produce pdf and epub.
>
>> CMake can read files into variables and it can process configure
>> files[1] which can produce any intermediate file we require for
>> processing.
>
> ok but I am not using and I am not able to use cmake anyway. I will try
> to port all the docs into this new format. When the port will be complete
> cmake people can (if they will) step in. I do not mean to be rude, mind
> me, just keep on discussing since I am not sure to see your point and
> that is probably my fault anyway...
>
>> Personally I really dislike documentation that's chopped up into
>> separate pages,
>
> not pages, chapters. So for this point we have find an agreement.
> See below...[XX]
>
>> the old CMake documentation is much better than the
>> new (presumably Sphinx generated) documentation for me.
>
> I do not have access to the CMake docs, I do not know and I cannot adjudicate.
>
>> One search of
>> the page always results in me getting results, whereas it doesn't in
>> the newly separated docs.
>
> Uhm that could be really a point to unite all the docs into one big file
> but perhaps it can be circunvented using the trick to unite all the docs
> into one big format before compiling... [XX] I am sure I am not the
> onlyone that find handier to have the big docs separated into chapters
> ... that could really kill two birds with one stone...
>
>> I'll start the CMake and will try and make use of Fat-Zer's starting
>> point. We have to test for a lot of features though to make it easy
>> for documentation builders.
>
> do you have a git report to follow your work?
>
>> I assume that translators will simply use something like poedit which
>> they'll be used to on the po files, is that right?
>
> right
>
>> So really, unless they're keen to see the built output,
>> the documentation build system shouldn't really trip them up anyway.
>
> well, seeing the output finished *before* committing the work is a really
> *plus* that I am not willing to renounce without a very good reason.
>
>> Hopefully we'll get CI building
>> of the docs and an automatic upload of at least one format to the web.
>
> That would be nice. Html output is the perfect format for the web, and it
> could easily be cross platform since it does not need any of the all
> other tools (docbook/latex/etc.) that complicate the toolchain.

Yes, I intend to make the CI do that. I am not sure where if the files
should be hosted (chached) somewhere out of the Jenkins workspace. I
was thinking pushing them to http://downloads.kicad-pcb.org/, but I
will wait fixing that untill we have cmake for the docs. Thank you.

>
> Thank for sharing your thoughts
>
> --
>
>
> Marco Ciampa