kicad-developers team mailing list archive

[Brian Sidebotham <brian.sidebotham@xxxxxxxxx>]

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, so don't worry too much about the
building of the docs. We don't need sed 'foo' or anything as we have
CMake and it can do everything we need *cross platform*.

CMake can read files into variables and it can process configure
files[1] which can produce any intermediate file we require for
processing.

Personally I really dislike documentation that's chopped up into
separate pages, the old CMake documentation is much better than the
new (presumably Sphinx generated) documentation for me. One search of
the page always results in me getting results, whereas it doesn't in
the newly separated docs.

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.

I assume that translators will simply use something like poedit which
they'll be used to on the po files, is that right? So really, unless
they're keen to see the built output, the documentation build system
shouldn't really trip them up anyway. Hopefully we'll get CI building
of the docs and an automatic upload of at least one format to the web.

[1] http://www.cmake.org/cmake/help/v2.8.12/cmake.html#command:configure_file

Best Regards,

Brian.