Documentation: Remove deprecated skeleton-update (issue 545910043 by jonas.hahnfeld@gmail.com)

classic Classic list List threaded Threaded
3 messages Options
Reply | Threaded
Open this post in threaded view
|

Documentation: Remove deprecated skeleton-update (issue 545910043 by jonas.hahnfeld@gmail.com)

jonas.hahnfeld
Reviewers: ,

Message:
As I'm not doing translations myself, it would be great if somebody
familiar with the process could comment on the faith of
scripts/auxiliar/texi-skeleton-update.py: It's not failing, but to me
doesn't look like doing anything helpful either.

Description:
Documentation: Remove deprecated skeleton-update

It's been like that since commit 858e506c2a in 2010, ten years ago.
Also remove target all-translations-update which cannot have worked
since the same time and update some CG pages mentioning the targets.

Completely ditch the section about 'Adding a Texinfo manual' because
it seems out-of-date with respect to the build system: Directories
with the included .itely files are not listed in SUBDIRS and have no
GNUmakefile that would need to be copied.

Please review this at https://codereview.appspot.com/545910043/

Affected files (+0, -59 lines):
  M Documentation/GNUmakefile
  M Documentation/contributor/doc-work.itexi


Index: Documentation/GNUmakefile
diff --git a/Documentation/GNUmakefile b/Documentation/GNUmakefile
index 070c3fdf51036ead951aff578fc51d39bac34a4d..4780356428ab815443abf839f2c0237cd9ad7b33 100644
--- a/Documentation/GNUmakefile
+++ b/Documentation/GNUmakefile
@@ -316,9 +316,6 @@ $(outdir)/internals.texi: $(LILYPOND_BINARY) $(INIT_LY_SOURCES) $(SCHEME_SOURCES
 po-update:
  $(MAKE) -C po po-update
 
-all-translations-update: po-update translation-status
- $(foreach lang, $(LANGS), $(MAKE) ISOLANG=$(lang) skeleton-update snippet-update &&) true
-
 ifneq ($(NO_COLOR),)
 CHECK_TRANSLATION_FLAGS = --no-color
 endif
@@ -351,16 +348,8 @@ new-lang:
 
 TRANSLATION_DIRS = web texidocs
 TRANSLATION_FILES = $(shell git ls-files $(ISOLANG) | grep -v GNUmakefile)
-TEXI_LANGUTIL_FLAGS += --skeleton
 
 TELY_FILES = $(call src-wildcard,$(ISOLANG)/*.tely)
-skeleton-update:
- @echo "$@ has been discontinued"
- @echo "simply copy .texi, .itexi files you want to translate"
- exit 2
- mkdir -p $(ISOLANG)
- $(PYTHON) $(auxscript-dir)/texi-langutils.py -d $(outdir) -l $(ISOLANG) $(TEXI_LANGUTIL_FLAGS) $(TELY_FILES:$(ISOLANG)/%.tely=../%.tely)
- $(PYTHON) $(auxscript-dir)/texi-skeleton-update.py $(ISOLANG) $(outdir)
 
 snippet-update:
  $(PYTHON) $(auxscript-dir)/update-snippets.py user $(ISOLANG) '*.itely'
Index: Documentation/contributor/doc-work.itexi
diff --git a/Documentation/contributor/doc-work.itexi b/Documentation/contributor/doc-work.itexi
index 1a91bf7ed9cfcb75f17453a6e53d19818cf8e6f2..7b048270fd0aed51dcc98b723f338c6e669769ff 100644
--- a/Documentation/contributor/doc-work.itexi
+++ b/Documentation/contributor/doc-work.itexi
@@ -1768,7 +1768,6 @@ All files should be encoded in UTF-8.
 @menu
 * Files to be translated::
 * Translating the Web site and other Texinfo documentation::
-* Adding a Texinfo manual::
 @end menu
 
 @node Files to be translated
@@ -1940,34 +1939,6 @@ and/or the Documentation Editors on @email{lilypond-devel@@gnu.org}
 list.
 
 
-@node Adding a Texinfo manual
-@unnumberedsubsubsec Adding a Texinfo manual
-
-In order to start translating a new manual whose basename is @var{FOO},
-do
-
-@example
-cd Documentation/@var{MY-LANGUAGE}
-cp ../@var{FOO}.tely .
-mkdir @var{FOO}
-cp web/GNUmakefile @var{FOO}
-@end example
-
-@noindent
-then append @var{FOO} to variable @code{SUBDIRS} in
-Documentation/@var{MY-LANGUAGE}/GNUmakefile, then translate file
-@var{MY-LANGUAGE}/@var{FOO}.tely and run @code{skeleton-update}:
-
-@example
-cd Documentation/
-make ISOLANG=@var{MY-LANGUAGE} TEXI_LANGUTIL_FLAGS=--head-only skeleton-update
-@end example
-
-@noindent
-Your are now ready to translate the new manual exactly like the web site
-or the Learning Manual.
-
-
 @node Documentation translation maintenance
 @subsection Documentation translation maintenance
 
@@ -2082,15 +2053,6 @@ the full file in English will be opened instead.
 
 @seeCommittishesUpdate
 
-Texinfo skeleton files, i.e. @file{.itely} files not yet translated,
-containing only the first node of the original file in English can be
-updated automatically: whenever @command{make check-translation} shows
-that such files should be updated, run from @file{Documentation/}
-
-@example
-make ISOLANG=@var{MY_LANGUAGE} skeleton-update
-@end example
-
 @file{.po} message catalogs in @file{Documentation/po/} may be updated
 by issuing from @file{Documentation/} or @file{Documentation/po/}
 
@@ -2125,16 +2087,6 @@ the changes it made with @command{git diff} before committing; if you
 don't do so, some @code{@@lilypond} snippets might be broken or make
 no sense in their context.
 
-Finally, a command runs the three update processes above for all
-enabled languages (from @file{Documentation/}):
-
-@example
-make all-translations-update
-@end example
-
-Use this command with caution, and keep in mind it will not be really
-useful until translations are stabilized after the end of GDP and GOP.
-
 @seealso
 @ref{Maintaining without updating translations},
 @ref{Adding and editing snippets}.



Reply | Threaded
Open this post in threaded view
|

Re: Documentation: Remove deprecated skeleton-update (issue 545910043 by jonas.hahnfeld@gmail.com)

Federico Bruni
On 2020/04/19 15:04:38, hahnjo wrote:
> As I'm not doing translations myself, it would be great if somebody
familiar
> with the process could comment on the faith of
> scripts/auxiliar/texi-skeleton-update.py: It's not failing, but to me
doesn't
> look like doing anything helpful either.

I remember I tried using it when I started the translation about 10
years ago and it wasn't helpful at all.
I'm Ok with removing it. Other translators will hopefully confirm (or
not).


However, I would not remove completely that section in the CG.
In general, the documentation doesn't take anything for granted,
especially when information is addressed to newcomers.
I would write something like:

"""
Adding a Texinfo manual

In order to start translating a new manual, simply copy the english
files within your language directory and translate them.
For example, if you want to translate the first chapter of the Learning
Manual:

cp Documentation/learning.tely Documentation/LANG/learning.tely
cp Documentation/learning/tutorial.itely
Documentation/LANG/tutorial.itely
"""



https://codereview.appspot.com/545910043/

Reply | Threaded
Open this post in threaded view
|

Re: Documentation: Remove deprecated skeleton-update (issue 545910043 by jonas.hahnfeld@gmail.com)

jonas.hahnfeld
In reply to this post by jonas.hahnfeld
On 2020/04/20 09:09:22, fedelogy wrote:
> On 2020/04/19 15:04:38, hahnjo wrote:
> > As I'm not doing translations myself, it would be great if somebody
familiar
> > with the process could comment on the faith of
> > scripts/auxiliar/texi-skeleton-update.py: It's not failing, but to
me doesn't
> > look like doing anything helpful either.
>
> I remember I tried using it when I started the translation about 10
years ago
> and it wasn't helpful at all.
> I'm Ok with removing it. Other translators will hopefully confirm (or
not).

I've removed it in the updated patch set. If somebody needs it after
this patch landed (which I'll delay a bit to give a fair chance for
objection), we can still restore it from the git history.

> However, I would not remove completely that section in the CG.
> In general, the documentation doesn't take anything for granted,
especially when
> information is addressed to newcomers.
> I would write something like:
>
> """
> Adding a Texinfo manual
>
> In order to start translating a new manual, simply copy the english
files within
> your language directory and translate them.
> For example, if you want to translate the first chapter of the
Learning Manual:
>
> cp Documentation/learning.tely Documentation/LANG/learning.tely
> cp Documentation/learning/tutorial.itely
Documentation/LANG/tutorial.itely
> """

Ah, that matches more closely what I would have expected. I've added
your text to the patch, thanks!

https://codereview.appspot.com/545910043/