kicad-developers team mailing list archive

[Marco Ciampa <ciampix@xxxxxxxxx>]

On Fri, Nov 03, 2017 at 08:55:54AM +0100, Carsten Schoenert wrote:
> Hello Wayne,
> 
> Am 03.11.2017 um 00:58 schrieb Wayne Stambaugh:
> > No one is going to argue that our documentation could be improved.  I'm
> > not really sure what the best approach would be to do that.  I would
> > prefer that we work with the tools and infrastructure we already have in
> > place rather than create a new dependency if at all possible.
> 
> nobody want's to introduce new tools or dependencies as long as there is
> no body that will do the work. And I agree with you, I see no need for
> something like that. The existing structure and tool-sets is working
> well so far.
> 
> >  What
> > about creating a documentation todo list asciidoc file in the
> > documentation repo.  The list would be broken down into two sections,
> > undocumented features and out of date/obsolete features.  Each section
> > can be broken down by application.  This would give folks looking to
> > help an idea of what needs to be done.
> 
> Yes and no, for existing topics that are poorly documented or need some
> refreshing due passed time with upstream changes this may work. And
> there are some kind of list already due some issues that are raised in
> the issue tracker on the repo site.

agree 100%

> But my starting posting was more about the currently new but completely
> undocumented features that come with version 5 of KiCad. I can't see any
> possible effort on that based on your proposal due "external" people
> mostly doesn't know what to document at all. At least within the last
> year there is no one single addition in progress here.

agree 100% see my previous post

> But the main English documentation needs to be ready before any
> translators should start. 

In an ideal world yes.

1) or at least if someone fixies some spelling errors in the English
language, he/she must also/is responsible to un-fuzzy the corrispondant
strings in all the other languages .po files

and

2) must do this after asking all translators to do commit their
translations to avoid nasty conflicts and race conditions. Merge works
only using some special filters that do not diff comments in translation
files (.po) for example...

The problem here is that to avoid loss of locally updated translations
during a merge, each translator should use a specific merge tool for .po
files. Perhaps this can be resolved with some scripting inserted in the
cmake files. Some operation like this:

make manualname_languagecode_update #contains a git pull ...
mkdir build; cd build; cmake ..; etc... #for check
git commit -a -m "Updated translation of MANUALNAME in LANGUAGE"


> I can remember some discussion there I wanted
> to change some spelling and formatting of the files in the master branch
> (not the 4.0 branch!) which wasn't accepted due the impact in every PO
> file down in the various languages. So I don't really want to put again
> some energy on that before things are clear.

Right see previous comment...

> We need some agreement first what needs or should be added to the
> documentation of KiCad5. If there is something like that existing we
> than need people who take care on that.

Agree again...

-- 


Marco Ciampa

I know a joke about UDP, but you might not get it.

------------------------

 GNU/Linux User #78271
 FSFE fellow #364

------------------------