kicad-developers team mailing list archive

[Brian Sidebotham <brian.sidebotham@xxxxxxxxx>]

On 9 February 2015 at 11:01, Marco Ciampa <ciampix@xxxxxxxxx> wrote:
> 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.

No, as a project we have not decided this, or if we did, I missed it
so please point me to the decision. The CMake build system must be
cross-platform and I'm sure has been specified in several other
emails. As always, email is a poor communication tool!

>> 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]

Each chapter is a page...

>> 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.

I included them in a reference and if you have access to the web you
have access to the CMake docs!?

>> 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?

No not yet, because as I said, I will start the work... I will let you
know when I have a repo together...

>> 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.

I am not suggesting that they *cannot* see it, I'm just saying that to
translate the documentation you don't necessarily *have* to go through
the build process, you can just edit the po files, and send a
patch/commit/pull request.

Thank-you for all your work on the text format documentation!

Best Regards,

Brian.