kicad-developers team mailing list archive

[Wayne Stambaugh <stambaughw@xxxxxxxxx>]

On 2/5/2015 9:45 AM, Fat-Zer wrote:
> 2015-02-05 16:52 GMT+03:00 Wayne Stambaugh <stambaughw@xxxxxxxxx>:
>> On 2/5/2015 5:03 AM, Fat-Zer wrote:
>>> 2015-02-04 19:52 GMT+03:00 Wayne Stambaugh <stambaughw@xxxxxxxxx>:
>>>>
>>>> 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.
>>>>
>>>> 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.
>>>>
>>> Hi, I've done some cmake macro scripting for building asciidoc based
>>> on Marco's repository some time ago:
>>> https://github.com/Fat-Zer/kicad-doc
>>> It's ready to use for generate output in several formats like docbook,
>>> pdf, html and other.
>>> But, by the word, it doesn't check some special additional
>>> dependencies for specific formats... may be I'll add a test if
>>> specified format may be build in future...
>>
>> This is important.  The build configuration should always test for
>> dependencies and fail during the configuration rather than fail during
>> the build for missing dependencies.  Brian has graciously offered to
>> help with the CMake stuff.  He has a lot of experience in this area.
>> Brian, would you please take a look at the CMake stuff and see what
>> needs to be done to get this production ready?  Once it's cleaned up, it
>> should be merged into Marco's branch so that the documentation and the
>> build configuration is in the same place.
> Yep, I like your concerns about failings and performing as much tests
> as possible during the configuration time, because IMO it's an
> important part of the build QA. On the other hand it's hard to track
> what specific dependencies are missing because a2x uses them
> indirectly. But that's about only formats processed by a2x like pdf
> epub etc. Docbook and html supposed to work whenever asciidoc works
> correct.

The solution is to create a small test doc and call a2x with the
appropriate switches and verify a2x doesn't fail.  You should be able to
test for all of the required a2x dependencies this way.  It's kind of
like writing a small C or C++ program to test if a compiler supports a
given feature.  This is one of the most accurate ways to test for
features.  The beauty of this method is that it will work for any platform.

> 
>>
>> Marco, you may want to enlist some help.  Once all of the documentation
>> and build configuration is ready to go, I expect that there will be a
>> lot of pull requests to get the documentation ready for the stable release.
>>
>> I haven't had time to look but is there any documentation on how to
>> contribute and create translations using the CMake configuration?  It
>> might be a good idea to provide this for new contributors.  I'm guessing
>> not all of our documentation folks are familiar with using cmake, git,
>> and github.  We want to make sure that it is as easy as possible for
>> folks to contribute documentation.
> Do you mean build translated documentation? Yes, they are build by
> default... you can alter the KICAD_DOC_TRANSLATIONS var to set the
> list of whatever specific languages you want to build.
> The translation process by it self is handled with an utility set
> called po4a. The creation of new and update of the existing
> translations is not yet supported by my cmake scripts.
> 
I just ant to make sure it's obvious to the documentation devs what
files to edit and how to build the documentation so they can verify
their work.  Using LibreOffice writer is pretty straight forward for
most of our translators.  There may be some who are not comfortable
running CMake and 'make foo' to build the documentation.