CG: add warnings for docs to Quick start.

[lilypond.git] / Documentation / contributor / doc-work.itexi

diff --git a/Documentation/contributor/doc-work.itexi b/Documentation/contributor/doc-work.itexi
index cab96b90a405ed5831f84a8a5c5d666637c4c38c..f74d1417b22712c969727ac0ee7fb23df7ccd596 100644 (file)
--- a/Documentation/contributor/doc-work.itexi
+++ b/Documentation/contributor/doc-work.itexi
@@ -193,18 +193,18 @@ to do anything fancy, discuss it on @code{lilypond-devel} first.}
 All manuals live in @file{Documentation/}.
 
 In particular, there are four user manuals, their respective master
 All manuals live in @file{Documentation/}.
 
 In particular, there are four user manuals, their respective master

-source files are @file{learning@/.tely} (LM, Learning Manual),
-@file{notation@/.tely} (NR, Notation Reference),
-@file{music@/-glossary@/.tely} (MG, Music Glossary), and
-@file{lilypond@/-program} (AU).  Each chapter is written in a separate
+source files are @file{learning.tely} (LM, Learning Manual),
+@file{notation.tely} (NR, Notation Reference),
+@file{music-glossary.tely} (MG, Music Glossary), and
+@file{lilypond-program} (AU).  Each chapter is written in a separate

 file, ending in @file{.itely} for files containing lilypond code, and
 @file{.itexi} for files without lilypond code, located in a subdirectory
 file, ending in @file{.itely} for files containing lilypond code, and
 @file{.itexi} for files without lilypond code, located in a subdirectory

-associated to the manual (@file{learning/} for @file{learning@/.tely}, and
+associated to the manual (@file{learning/} for @file{learning.tely}, and

 so on); list the subdirectory of each manual to determine the filename
 of the specific chapter you wish to modify.
 
 Developer manuals live in @file{Documentation/} too.  Currently there is
 so on); list the subdirectory of each manual to determine the filename
 of the specific chapter you wish to modify.
 
 Developer manuals live in @file{Documentation/} too.  Currently there is

-only one: the Contributor's Guide @file{contrib@/-guide@/.texi} you are
+only one: the Contributor's Guide @file{contrib-guide.texi} you are

 reading.
 
 Snippet files are part of documentation, and the Snippet List (SL) lives
 reading.
 
 Snippet files are part of documentation, and the Snippet List (SL) lives


@@ -340,6 +340,14 @@ or
 @@lilypond[verbatim,quote,relative=1]
 @end example
 
 @@lilypond[verbatim,quote,relative=1]
 @end example
 

+Please avoid using extra spacing either after or within the
+@code{@@lilypond} parameters.
+
+@example
+not:          @@lilypond [verbatim, quote, relative=1]
+but instead:  @@lilypond[verbatim,quote,relative=1]
+@end example
+

 If you want to use @code{\layout@{@}} or define variables, use
 
 @example
 If you want to use @code{\layout@{@}} or define variables, use
 
 @example


@@ -604,17 +612,20 @@ external url.  Use within an @code{@@example ... @@end example}.
 @item
 @code{@@code@{@dots{}@}}, @code{@@samp@{@dots{}@}} ---
 
 @item
 @code{@@code@{@dots{}@}}, @code{@@samp@{@dots{}@}} ---
 

-Use the @code{@@code@{@dots{}@}} command for individual
-language-specific tokens (keywords, commands, engravers, scheme
-symbols, etc.).  Ideally, a single @code{@@code@{@dots{}@}} block
-should fit within one line in the PDF output.  Use the
-@code{@@samp@{@dots{}@}} command when you have a short example of
-user input, unless it constitutes an entire @code{@@item} by
-itself, in which case @code{@@code@{@dots{}@}} is preferable.
-Otherwise, both should only be used when part of a larger sentence
-within a paragraph or @code{@@item}.  Never use a
-@code{@@code@{@dots{}@}} or @code{@@samp@{@dots{}@}} block as a
-free-standing paragraph; use @code{@@example} instead.
+Use the @code{@@code@{@dots{}@}} command when referring to
+individual language-specific tokens (keywords, commands,
+engravers, scheme symbols, etc.) in the text.  Ideally, a single
+@code{@@code@{@dots{}@}} block should fit within one line in the
+PDF output.
+
+Use the @code{@@samp@{@dots{}@}} command when you have a short
+example of user input, unless it constitutes an entire
+@code{@@item} by itself, in which case @code{@@code@{@dots{}@}} is
+preferable.  Otherwise, both should only be used when part of a
+larger sentence within a paragraph or @code{@@item}.  Do not use
+@code{@@code@{@dots{}@}} or @code{@@samp@{@dots{}@}} inside an
+@code{@@example} block, and do not use either as a free-standing
+paragraph; use @code{@@example} instead.

 
 A single unindented line in the PDF has space for about 79
 fixed-width characters (76 if indented).  Within an @code{@@item}
 
 A single unindented line in the PDF has space for about 79
 fixed-width characters (76 if indented).  Within an @code{@@item}


@@ -660,8 +671,9 @@ so the example above would be coded as
 @q{@code{@@q@{@@w@{@@code@{@@bs@{@}relative c''@}@}@}}}.
 
 @item
 @q{@code{@@q@{@@w@{@@code@{@@bs@{@}relative c''@}@}@}}}.
 
 @item

-@code{@@command@{@dots{}@}} --- Use for command-line commands (eg.
-@samp{@@command@{lilypond-book@}}).
+@code{@@command@{@dots{}@}} --- Use when referring to command-line
+commands within the text (eg. @samp{@@command@{convert-ly@}}).  Do
+not use inside an @code{@@example} block.

 
 @item
 @code{@@example} --- Use for examples of program code.  Do not add
 
 @item
 @code{@@example} --- Use for examples of program code.  Do not add


@@ -700,11 +712,14 @@ running into the PDF margin.  Each additional level of
 @code{@@smallexample} line by about 5 columns.
 
 @item
 @code{@@smallexample} line by about 5 columns.
 
 @item

-@code{@@file@{@dots{}@}} --- Use for filenames and directories.
+@code{@@file@{@dots{}@}} --- Use when referring to filenames and
+directories in the text.  Do not use inside an @code{@@example}
+block.

 
 @item
 
 @item

-@code{@@option@{@dots{}@}} --- Use for options to command-line
-commands (eg. @samp{@@option@{--format@}}).
+@code{@@option@{@dots{}@}} --- Use when referring to command-line
+options in the text (eg. @samp{@@option@{--format@}}).  Do not use
+inside an @code{@@example} block.

 
 @item
 @code{@@verbatim} --- Prints the block exactly as it appears in
 
 @item
 @code{@@verbatim} --- Prints the block exactly as it appears in


@@ -741,16 +756,33 @@ Don't capitalize the first word.
 @itemize
 @item
 @code{@@enumerate} --- Create an ordered list (with numbers).
 @itemize
 @item
 @code{@@enumerate} --- Create an ordered list (with numbers).

-Always put @samp{@@item} on its own line, and separate consecutive
-items with a blank line:
+Always put @samp{@@item} on its own line.  As an exception, if all
+the items in the list are short enough to fit on single lines, placing
+them on the @samp{@@item} lines is also permissible.  @samp{@@item}
+and @samp{@@end@tie{}enumerate} should always be preceded by a blank
+line.

 
 @example
 @@enumerate
 
 @example
 @@enumerate

+

 @@item
 @@item

-Foo
+A long multi-line item like this one must begin
+on a line of its own and all the other items in
+the list must do so too.

 
 @@item
 
 @@item

-Bar
+Even short ones
+
+@@end enumerate
+@end example
+
+@example
+@@enumerate
+
+@@item Short item
+
+@@item Short item
+

 @@end enumerate
 @end example
 
 @@end enumerate
 @end example
 


@@ -814,7 +846,17 @@ Only use once per subsection per term.
 backslash (\), you must use @samp{@@bs@{@}}.
 
 @item
 backslash (\), you must use @samp{@@bs@{@}}.
 
 @item

-@code{@@var@{@dots{}@}} --- Use for variables.
+@code{@@var@{@dots{}@}} --- Use for metasyntactic variables (such
+as @code{@var{foo}}, @code{@var{bar}}, @code{@var{arg1}}, etc.).
+In most cases, when the @code{@@var@{@dots{}@}} command appears in
+the text (and not in an @code{@@example} block) it should be
+wrapped with an appropriate texinfo code-highlighting command
+(such as @code{@@code}, @code{@@samp}, @code{@@file},
+@code{@@command}, etc.).  For example:
+@samp{@@code@{@@var@{foo@}@}},
+@samp{@@file@{@@var@{myfile.ly@}@}},
+@w{@samp{@@samp@{git checkout @@var@{branch@}@}}}, etc.  This
+improves readability in the PDF and HTML output.

 
 @item
 @code{@@version@{@}} --- Return the current LilyPond version
 
 @item
 @code{@@version@{@}} --- Return the current LilyPond version


@@ -946,7 +988,7 @@ write: DYNAMICS may be manually placed above or below the staff,
 see @@ref@{Controlling direction and placement@}.
 
 Most tweaks should be added to LSR and not placed directly in the
 see @@ref@{Controlling direction and placement@}.
 
 Most tweaks should be added to LSR and not placed directly in the

-.itely file.  In some cases, tweaks may be placed in the main
+@file{.itely} file.  In some cases, tweaks may be placed in the main

 text, but ask about this first.
 
 Finally, you should assume that users know what the notation
 text, but ask about this first.
 
 Finally, you should assume that users know what the notation


@@ -1059,7 +1101,7 @@ manual.
 
 @item
 @@predefined ... @@endpredefined is for commands in
 
 @item
 @@predefined ... @@endpredefined is for commands in

-@file{ly/@/*-init@/.ly}
+@file{ly/*-init.ly}

 
 @item
 Do not include any real info in second-level sections (i.e. 1.1
 
 @item
 Do not include any real info in second-level sections (i.e. 1.1


@@ -1067,6 +1109,14 @@ Pitches).  A first-level section may have introductory material,
 but other than that all material goes into third-level sections
 (i.e. 1.1.1 Writing Pitches).
 
 but other than that all material goes into third-level sections
 (i.e. 1.1.1 Writing Pitches).
 

+@item
+The @@knownissues should not discuss any issues that are in the
+tracker, unless the issue is Priority-Postponed.  The goal is to
+discuss any overall architecture or syntax decisions which may be
+interpreted as bugs.  Normal bugs should not be discussed here,
+because we have so many bugs that it would be a huge task to keep
+the @@knownissues current and accurate all the time.
+

 @end itemize
 
 
 @end itemize
 
 


@@ -1114,23 +1164,24 @@ Enter commands with @@funindex, i.e.
 @end example
 
 @noindent
 @end example
 
 @noindent

-do not bother with the @@code@{@} (they are added automatically).
+Do not bother with the @@code@{@} (they are added automatically).

 These items are added to both the command index and the unified
 These items are added to both the command index and the unified

-index.
+index.  Both index commands should go in front of the actual material.

 
 

-Both index commands should go in front of the actual material.
-
-@@cindex entries should not be capitalized, ie
+@item
+@@cindex entries should not be capitalized, i.e.

 
 @example
 @@cindex time signature
 @end example
 
 @noindent
 
 @example
 @@cindex time signature
 @end example
 
 @noindent

-is preferred instead of @qq{Time signature},   Only use capital
-letters for musical terms which demand them, like D.S. al Fine.
+is preferred instead of @qq{Time signature}.  Only use capital
+letters for musical terms which demand them, e.g.
+@qq{D.S. al Fine}.

 
 

-For scheme functions, only include the final part, i.e.,
+@item
+For scheme function index entries, only include the final part, i.e.

 
 @example
 @@funindex modern-voice-cautionary
 
 @example
 @@funindex modern-voice-cautionary


@@ -1139,28 +1190,41 @@ For scheme functions, only include the final part, i.e.,
 @end example
 
 @item
 @end example
 
 @item

-Preferred terms:
+Use American spelling.  LilyPond's internal property
+names use this convention.
+
+@item
+Here is a list of preferred terms to be used:

 
 @itemize
 
 @itemize

+@item
+@emph{Simultaneous} NOT concurrent.

 
 @item
 
 @item

-In general, use the American spellings.  The internal lilypond
-property names use this spelling.
+@emph{Measure}: the unit of music.

 
 @item
 
 @item

-List of specific terms:
+@emph{Bar line}: the symbol delimiting a measure NOT barline.

 
 

-@example
-canceled
-simultaneous    NOT concurrent
-measure: the unit of music
-bar line: the symbol delimiting a measure   NOT barline
-note head   NOT notehead
-chord construct   NOT chord (when referring to <>)
-@end example
+@item
+@emph{Note head} NOT notehead.
+
+@item
+@emph{Chord construct} NOT just chord (when referring to < ... >)
+
+@item
+@emph{Staff} NOT stave.
+
+@item
+@emph{Staves} NOT Staffs:
+Phrases such as
+@q{multiple @@internalsref@{Staff@}s}
+should be rephrased to
+@q{multiple @@internalsref@{Staff@} contexts}.

 
 @end itemize
 
 
 @end itemize
 

+

 @end itemize
 
 
 @end itemize
 
 


@@ -1224,7 +1288,7 @@ concern.  Check for potential additions.
 
 @item
 move LSR-worthy material into LSR.  Add the snippet, delete the
 
 @item
 move LSR-worthy material into LSR.  Add the snippet, delete the

-material from the .itely file, and add a @@lilypondfile command.
+material from the @file{.itely} file, and add a @@lilypondfile command.

 
 @item
 check the examples and descriptions.  Do they still work?
 
 @item
 check the examples and descriptions.  Do they still work?


@@ -1253,7 +1317,7 @@ harder than it looks.
 
 In general, any \set or \override commands should go in the
 @qq{select snippets} section, which means that they should go in
 
 In general, any \set or \override commands should go in the
 @qq{select snippets} section, which means that they should go in

-LSR and not the .itely file.  For some cases, the command
+LSR and not the @file{.itely} file.  For some cases, the command

 obviously belongs in the @qq{main text} (i.e. not inside
 @@predefined or @@seealso or whatever) -- instrument names are a
 good example of this.
 obviously belongs in the @qq{main text} (i.e. not inside
 @@predefined or @@seealso or whatever) -- instrument names are a
 good example of this.


@@ -1325,7 +1389,7 @@ scripts/auxiliar/doc-section.sh MANUAL SECTION
 
 @noindent
 where @code{SECTION} is the name of the file containing the section
 
 @noindent
 where @code{SECTION} is the name of the file containing the section

-to be build, and @code{MANUAL} isc replaced by the name of the directory
+to be built, and @code{MANUAL} is replaced by the name of the directory

 containing the section.  So, for example, to build section 1.1 of the
 Notation Reference, use the command:
 
 containing the section.  So, for example, to build section 1.1 of the
 Notation Reference, use the command:
 


@@ -1353,46 +1417,35 @@ scripts/auxiliar/cg-section.sh doc-work
 Like @code{doc-section.sh}, @code{cg-section.sh} may need to be customized
 for your installation.
 
 Like @code{doc-section.sh}, @code{cg-section.sh} may need to be customized
 for your installation.
 

-@subheading Stripping whitespace
+@subheading Stripping whitespace and generating menus

 
 

-@c TODO: should this be documented elsewhere?  It's useful for
-@c more than just docs.
-To remove extra whitespace from the ends of lines, run
+@warning{This script assumes that the file conforms to our doc
+policy; a few files still need work in this regard.}
+
+To automatically regenerate @code{@@menu} portions and strip
+whitespace, use:

 
 @example
 
 @example

-scripts/auxiliar/strip-whitespace.py Documentation/FILENAME
+scripts/auxiliar/node-menuify.py @var{FILENAME}

 @end example
 
 
 @end example
 
 

-@subheading Sectioning commands
-
-@warning{These commands add whitespace.}
+@subheading Stripping whitespace only

 
 

-The emacs @code{M-x texinfo-all-menus-update} command will
-regenerate @@menu blocks.  This can also be run with this
-command-line script:
+@c TODO: should this be documented elsewhere?  It's useful for
+@c more than just docs.
+To remove extra whitespace from the ends of lines, run

 
 @example
 
 @example

-#!/bin/sh
-emacs $1 -batch -f texinfo-all-menus-update -f save-buffer
+scripts/auxiliar/strip-whitespace.py Documentation/FILENAME

 @end example
 
 @end example
 

-@noindent
-(save the above as something like @command{texinfo-menus.sh}, make
-it executable, then run @command{texinfo-menus.sh foo.itely})
-

 
 @subheading Updating doc with @command{convert-ly}
 
 
 @subheading Updating doc with @command{convert-ly}
 

-cd into @file{Documentation/} and run
-
-@example
-find . -name '*.itely' | xargs convert-ly -e
-@end example
-
-@noindent
-This also updates translated documentation.
-
+Don't.  This should be done by programmers when they add new
+features.  If you notice that it hasn't been done, complain to
+@code{lilypond-devel}.

 
 
 @node Docstrings in scheme
 
 
 @node Docstrings in scheme


@@ -1400,7 +1453,7 @@ This also updates translated documentation.
 
 Material in the Internals reference is generated automatically
 from our source code.  Any doc work on Internals therefore
 
 Material in the Internals reference is generated automatically
 from our source code.  Any doc work on Internals therefore

-requires modifying files in @file{scm/@/*.scm}.  Texinfo is allowed
+requires modifying files in @file{scm/*.scm}.  Texinfo is allowed

 in these docstrings.
 
 Most documentation writers never touch these, though.  If you want
 in these docstrings.
 
 Most documentation writers never touch these, though.  If you want


@@ -1523,7 +1576,7 @@ make ISOLANG=@var{MY-LANGUAGE} new-lang
 where @var{MY-LANGUAGE} is the ISO 639 language code.
 
 Finally, add a language definition for your language in
 where @var{MY-LANGUAGE} is the ISO 639 language code.
 
 Finally, add a language definition for your language in

-@file{python/@/langdefs@/.py}.
+@file{python/langdefs.py}.

 
 
 @node Documentation translation details
 
 
 @node Documentation translation details


@@ -1641,19 +1694,19 @@ script @command{texi-langutils.py} and the makefile target are updated.
 
 Some pieces of text manipulated by build scripts that appear in the
 output are translated in a @file{.po} file -- just like LilyPond output
 
 Some pieces of text manipulated by build scripts that appear in the
 output are translated in a @file{.po} file -- just like LilyPond output

-messages -- in @file{Documentation/@/po}.  The Gettext domain is named
+messages -- in @file{Documentation/po}.  The Gettext domain is named

 @code{lilypond-doc}, and unlike @code{lilypond} domain it is not managed
 through the Free Translation Project.
 
 
 Take care of using typographic rules for your language, especially in
 @code{lilypond-doc}, and unlike @code{lilypond} domain it is not managed
 through the Free Translation Project.
 
 
 Take care of using typographic rules for your language, especially in

-@file{macros@/.itexi}.
+@file{macros.itexi}.

 
 If you wonder whether a word, phrase or larger piece of text should be
 translated, whether it is an argument of a Texinfo command or a small
 piece sandwiched between two Texinfo commands, try to track whether and
 where it appears in PDF and/or HTML output as visible text.  This piece
 
 If you wonder whether a word, phrase or larger piece of text should be
 translated, whether it is an argument of a Texinfo command or a small
 piece sandwiched between two Texinfo commands, try to track whether and
 where it appears in PDF and/or HTML output as visible text.  This piece

-of advice is especially useful for translating @file{macros@/.itexi}.
+of advice is especially useful for translating @file{macros.itexi}.

 
 Please keep verbatim copies of music snippets (in @code{@@lilypond}
 blocs).  However, some music snippets containing text that shows in
 
 Please keep verbatim copies of music snippets (in @code{@@lilypond}
 blocs).  However, some music snippets containing text that shows in


@@ -1679,15 +1732,15 @@ When you encounter
 @end example
 
 @noindent
 @end example
 
 @noindent

-in the source, open @file{Documentation/@/snippets/@/@var{filename}@/.ly},
+in the source, open @file{Documentation/snippets/@var{filename}.ly},

 translate the @code{texidoc} header field it contains, enclose it with
 @code{texidoc@var{MY-LANGUAGE} = "} and @code{"}, and write it into
 translate the @code{texidoc} header field it contains, enclose it with
 @code{texidoc@var{MY-LANGUAGE} = "} and @code{"}, and write it into

-@file{Documentation/@/@var{MY-LANGUAGE}/@/texidocs/@/@var{filename}@/.texidoc}.
+@file{Documentation/@var{MY-LANGUAGE}/texidocs/@/@var{filename}.texidoc}.

 Additionally, you may translate the snippet's title in @code{doctitle}
 header field, in case @code{doctitle} is a fragment option used in
 @code{@@lilypondfile}; you can do this exactly the same way as
 @code{texidoc}.  For instance,
 Additionally, you may translate the snippet's title in @code{doctitle}
 header field, in case @code{doctitle} is a fragment option used in
 @code{@@lilypondfile}; you can do this exactly the same way as
 @code{texidoc}.  For instance,

-@file{Documentation/@/@var{MY-LANGUAGE}/@/texidocs/@/@var{filename}@/.texidoc}
+@file{Documentation/@var{MY-LANGUAGE}/texidocs/@/@var{filename}.texidoc}

 may contain
 
 @example
 may contain
 
 @example


@@ -1699,7 +1752,7 @@ Spanish translation blah
 
 @noindent
 Then, you should get these translated strings into compiled snippets in
 
 @noindent
 Then, you should get these translated strings into compiled snippets in

-@file{Documentation/@/snippets}, see @q{General guidelines} in @ref{Adding
+@file{Documentation/snippets}, see @q{General guidelines} in @ref{Adding

 and editing snippets}.
 
 @code{@@example} blocks need not be verbatim copies, e.g. variable
 and editing snippets}.
 
 @code{@@example} blocks need not be verbatim copies, e.g. variable


@@ -1814,7 +1867,7 @@ to make your translation up to date.
 @seeCommittishesUpdate
 
 Global state of the translation is recorded in
 @seeCommittishesUpdate
 
 Global state of the translation is recorded in

-@file{Documentation/@/translations@/.itexi}, which is used to generate
+@file{Documentation/translations.itexi}, which is used to generate

 Translations status page.  To update that page, do from
 @file{Documentation/}
 
 Translations status page.  To update that page, do from
 @file{Documentation/}
 


@@ -1822,7 +1875,7 @@ Translations status page.  To update that page, do from
 make translation-status
 @end example
 
 make translation-status
 @end example
 

-This will also leave @file{out/@/translations@/-status@/.txt}, which contains
+This will also leave @file{out/translations-status.txt}, which contains

 up-to-dateness percentages for each translated file, and update word
 counts of documentation files in this Guide.
 
 up-to-dateness percentages for each translated file, and update word
 counts of documentation files in this Guide.
 


@@ -1864,8 +1917,8 @@ that such files should be updated, run from @file{Documentation/}
 make ISOLANG=@var{MY_LANGUAGE} skeleton-update
 @end 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/}
+@file{.po} message catalogs in @file{Documentation/po/} may be updated
+by issuing from @file{Documentation/} or @file{Documentation/po/}

 
 @example
 make po-update
 
 @example
 make po-update


@@ -1886,8 +1939,8 @@ make ISOLANG=@var{MY_LANGUAGE} snippet-update
 @end example
 
 This script overwrites music snippets in
 @end example
 
 This script overwrites music snippets in

-@file{@var{MY_LANGUAGE/@/foo/@/every@/.itely}} with music snippets from
-@file{@var{foo/@/every@/.itely}}.  It ignores skeleton files, and keeps
+@file{@var{MY_LANGUAGE/foo/every.itely}} with music snippets from
+@file{@var{foo/every.itely}}.  It ignores skeleton files, and keeps

 intact music snippets preceded with a line starting with @code{@@c
 KEEP LY}; it reports an error for each @file{.itely} that has not the
 same music snippet count in both languages.  Always use this script
 intact music snippets preceded with a line starting with @code{@@c
 KEEP LY}; it reports an error for each @file{.itely} that has not the
 same music snippet count in both languages.  Always use this script


@@ -1897,8 +1950,8 @@ don't do so, some @code{@@lilypond} snippets might be broken or make
 no sense in their context.
 
 When you have updated texidocs in
 no sense in their context.
 
 When you have updated texidocs in

-@file{Documentation/@/@var{MY-LANGUAGE}/@/texidocs}, you can get these
-changes into compiled snippets in @file{Documentation/@/snippets}, see
+@file{Documentation/@var{MY-LANGUAGE}/texidocs}, you can get these
+changes into compiled snippets in @file{Documentation/snippets}, see

 @q{General guidelines} in @ref{Adding and editing snippets}.
 
 Finally, a command runs the three update processes above for all
 @q{General guidelines} in @ref{Adding and editing snippets}.
 
 Finally, a command runs the three update processes above for all


@@ -1936,12 +1989,12 @@ git rev-list HEAD |head -1
 @end example
 
 A special case is updating Snippet documentation strings in
 @end example
 
 A special case is updating Snippet documentation strings in

-@file{Documentation/@/@var{MY-LANGUAGE}/@/texidocs}.  For these to be
+@file{Documentation/@var{MY-LANGUAGE}/texidocs}.  For these to be

 correctly marked as up-to-date, first run @code{makelsr.py} as
 explained in @ref{Adding and editing snippets}, and commit the
 correctly marked as up-to-date, first run @code{makelsr.py} as
 explained in @ref{Adding and editing snippets}, and commit the

-resulting compiled snippets left in @file{Documentation/@/snippets/}.
+resulting compiled snippets left in @file{Documentation/snippets/}.

 Say the SHA1 ID code of this commit is <C>.  Now edit again your
 Say the SHA1 ID code of this commit is <C>.  Now edit again your

-translated files in @file{Documentation/@/@var{MY-LANGUAGE}/@/texidocs}
+translated files in @file{Documentation/@var{MY-LANGUAGE}/texidocs}

 adjusting the 40-digit committish that appears in the text to be <C>;
 finally, commit these updated files.  Not doing so would result in
 changes made both to your updates and original snippets to
 adjusting the 40-digit committish that appears in the text to be <C>;
 finally, commit these updated files.  Not doing so would result in
 changes made both to your updates and original snippets to


@@ -1992,9 +2045,9 @@ The following tasks are listed in decreasing priority order.
 @item Update macros.itexi.
 For each obsolete macro definition, if it is possible to update macro
 usage in documentation with an automatic text or regexp substitution,
 @item Update macros.itexi.
 For each obsolete macro definition, if it is possible to update macro
 usage in documentation with an automatic text or regexp substitution,

-do it and delete the macro definition from macros.itexi; otherwise,
+do it and delete the macro definition from @file{macros.itexi}; otherwise,

 mark this macro definition as obsolete with a comment, and keep it in
 mark this macro definition as obsolete with a comment, and keep it in

-macros.itexi until the documentation translation has been updated and
+@file{macros.itexi} until the documentation translation has been updated and

 no longer uses this macro.
 
 @item Update @file{*.tely} files completely with
 no longer uses this macro.
 
 @item Update @file{*.tely} files completely with


@@ -2158,7 +2211,7 @@ without updating translations}.
 
 A number of Python scripts handle a part of the documentation
 translation process.  All scripts used to maintain the translations
 
 A number of Python scripts handle a part of the documentation
 translation process.  All scripts used to maintain the translations

-are located in @file{scripts/@/auxiliar/}.
+are located in @file{scripts/auxiliar/}.

 
 @itemize
 @item @file{check_translation.py}  -- show diff to update a translation,
 
 @itemize
 @item @file{check_translation.py}  -- show diff to update a translation,


@@ -2174,21 +2227,21 @@ in the sources; WARNING only use this script once for each file, when support fo
 "makeinfo --html" has been dropped.
 @end itemize
 
 "makeinfo --html" has been dropped.
 @end itemize
 

-Other scripts are used in the build process, in @file{scripts/@/build/}:
+Other scripts are used in the build process, in @file{scripts/build/}:

 
 @itemize
 @item @file{mass-link.py} -- link or symlink files between English documentation
 and documentation in other languages.
 @end itemize
 
 
 @itemize
 @item @file{mass-link.py} -- link or symlink files between English documentation
 and documentation in other languages.
 @end itemize
 

-Python modules used by scripts in @file{scripts/@/auxiliar/} or @file{scripts/@/build/} (but
-not by installed Python scripts) are located in @file{python/@/auxiliar/}:
+Python modules used by scripts in @file{scripts/auxiliar/} or @file{scripts/build/} (but
+not by installed Python scripts) are located in @file{python/auxiliar/}:

 @itemize
 @item @file{manuals_definitions.py} -- define manual names and name of
 cross-reference Texinfo macros,
 @item @file{buildlib.py} -- common functions (read piped output
 of a shell command, use Git),
 @itemize
 @item @file{manuals_definitions.py} -- define manual names and name of
 cross-reference Texinfo macros,
 @item @file{buildlib.py} -- common functions (read piped output
 of a shell command, use Git),

-@item @file{postprocess_html.py} (module imported by @file{www_post@/.py}) -- add footer and
+@item @file{postprocess_html.py} (module imported by @file{www_post.py}) -- add footer and

 tweak links in HTML pages.
 @end itemize
 
 tweak links in HTML pages.
 @end itemize