Difference of documentation structures

classic Classic list List threaded Threaded
8 messages Options
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Difference of documentation structures

Yoshiki Sawada
Hello everyone,

Structures of documentation are different between English and other languages,
e.g., in LM:
==== LM in English ====
1. Introduction
  1.1 Compiling a file
  1.2 How to write input files
  1.3 How to read the manuals
2. Common notation
  2.1 Single staff notation
  2.2 Multiple notes at once
  2.3 Songs
  2.4 Final touches
...
==== LM in other languages ====
Preface
1. Introduction
  1.1 Context
  1.2 About this documentation
2. Tutorial
  2.1 First steps
  2.2 Single staff notation
  2.3 Multiple notes at once
  2.4 Songs
  2.5 Final touches
...
====

Why is that?
And which structure should I follow?

Sincerely,
Yoshiki Sawada
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Difference of documentation structures

Francisco Vila
2009/9/21 Yoshiki Sawada <[hidden email]>:
> Hello everyone,
>
> Structures of documentation are different between English and other
> languages,
> Why is that?
> And which structure should I follow?

All documentation work is done in English first and it has been deeply
reorganized recently.  To keep our translations in sync we should
clone English structure and contents.

To have a preview of what amount of work do you have to do, issue this
command on Documentation/ :

    make ISOLANG=ja check-translation

I have a script that shows my progress comparing previous and current
output, I dump the output to a file and count its lines:

  wc -l ct
  make ISOLANG=es check-translation &>ct
  wc -l ct

where 'ct' is for 'check translations'.  Then I can inspect the
contents of ct by

  less -R ct

which preserves the colours of the diff.

For example, my ct is currently 25.000+ lines worth.

--
Francisco Vila. Badajoz (Spain)
www.paconet.org
www.csmbadajoz.com


Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Difference of documentation structures

Till Paala
In reply to this post by Yoshiki Sawada
Hi,

Yoshiki Sawada schrieb:
>
> Why is that?
> And which structure should I follow?
As Francisco already said, the English version is the right one, and
this one has been reorganized. I have started the reorganization for the
LM in German, so there are already the files/sections you mentioned, but
only in GIT so far. Most of the new LM 1 is indeed new, except 1.2 and
1.3, which come from tutorial. section 2 is the latter part of the
former tutorial. The old introduction consited of 1.1 which has been
moved to an entirely new document: essay.tely, which includes now also
literature.itely from the NR. 1.2 has been dropped, AFAICT.

It is indeed a total mess, and sometimes it appears to me that it would
be easier to translate it all anew. Maybe it is worth waiting some other
month until the reorganization has slowed down and we can be sure that
there won't be any changes coming in terms of reorganization. I hope
John will keep us informed about what is going on.
>
> Sincerely,
> Yoshiki Sawada
Greetings
Till



Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Difference of documentation structures

Francisco Vila
2009/9/21 Till Paala <[hidden email]>:
> It is indeed a total mess, and sometimes it appears to me that it would be
> easier to translate it all anew.

Exactly!

But there is a faster path: start from a skeleton for the target
document which has the final structure from the English model.  Then
fill its sections one a time.
--
Francisco Vila. Badajoz (Spain)
www.paconet.org
www.csmbadajoz.com


Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Difference of documentation structures

Yoshiki Sawada
All documentation work is done in English first and it has been deeply
reorganized recently.  To keep our translations in sync we should
clone English structure and contents.

I see. Thanks.

 Maybe it is worth waiting some other month until the reorganization has slowed down and we can be sure that there won't be any changes coming in terms of reorganization.

I'm sure.
I should make translation of NR progress instead of following the reorganization.

But there is a faster path: start from a skeleton for the target
document which has the final structure from the English model.  Then
fill its sections one a time.

Yes, this method looks better.
When I restart my reorganization, I will use this way.

Thanks,
Sawada, Yoshiki (Japan)
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Difference of documentation structures

Till Paala
In reply to this post by Francisco Vila
Francisco Vila schrieb:
2009/9/21 Till Paala [hidden email]:
  
It is indeed a total mess, and sometimes it appears to me that it would be
easier to translate it all anew.
    

Exactly!

But there is a faster path: start from a skeleton for the target
document which has the final structure from the English model.  Then
fill its sections one a time.
  
Yes, that's a great idea! I realized recently that the application manual (or how it is called nowadays) has also undergone severe changes, I guess I will apply your method for that one.

Till
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Difference of documentation structures

Francisco Vila
2009/9/22 Till Paala <[hidden email]>:
> Yes, that's a great idea! I realized recently that the application manual
> (or how it is called nowadays) has also undergone severe changes, I guess I
> will apply your method for that one.

BTW, beware of

  make ISOLANG=lang skeleton-update

this still puts skeletons outside of the folders as the old structure
did.  Also, they are not skeletons, but rather some kind of
intermediate texinfo files.
--
Francisco Vila. Badajoz (Spain)
www.paconet.org
www.csmbadajoz.com


Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Difference of documentation structures

John Mandereau
In reply to this post by Till Paala
Dear translators,
Le lundi 21 septembre 2009 à 23:05 +0300, Till Paala a écrit :
> It is indeed a total mess, and sometimes it appears to me that it would
> be easier to translate it all anew. Maybe it is worth waiting some other
> month until the reorganization has slowed down and we can be sure that
> there won't be any changes coming in terms of reorganization. I hope
> John will keep us informed about what is going on.

I'm little informed on this (Graham makes changes weeks after they have
been discussed a little on -user list), but I'll strive to update the
priority list before I become almost disconnected (from Wednesday Sep.
30 to Sunday Oct. 4).  Unfortunately, I'm as busy as many of you so I
can't keep up with all traffic on -user and thus it's difficult to
inform you reliably :-(

Sorry for the mess,
John

signature.asc (204 bytes) Download Attachment
Loading...