The Summary is now generated from @standards, and syntax-checking is
performed. If invalid @standards syntax is detected, summary.pl will
fail, reporting all errors. Failure and error reporting is disabled
for now, however, since much of the manual is still incomplete
wrt. header and standards annotations.
Note that the sorting order of the Summary has changed; summary.pl
respects the locale, like summary.awk did, but the use of LC_ALL=C is
introduced in the Makefile. Other notable deviations are improved
detection of the annotated elements' names, which are used for
sorting, and improved detection of the @node used to reference into
the manual. The most noticeable difference in the rendered Summary is
that entries may now contain multiple lines, one for each header and
standard combination.
summary.pl accepts a `--help' option, which details the expected
syntax of @standards. If errors are reported, the user is directed to
this feature for further information.
* manual/Makefile: Generate summary.texi with summary.pl.
Force use of the C locale. Update Perl dependency comment.
* manual/header.texi: Update reference to summary.awk.
* manual/macros.texi: Refer authors to `summary.pl --help'.
* manual/summary.awk: Remove file.
* manual/summary.pl: New file. Generate summary.texi, and
check for @standards-related syntax errors.
* manual/argp.texi: Convert header and standards @comments to
@standards.
* manual/arith.texi: Likewise.
* manual/charset.texi: Likewise.
* manual/conf.texi: Likewise.
* manual/creature.texi: Likewise.
* manual/crypt.texi: Likewise.
* manual/ctype.texi: Likewise.
* manual/debug.texi: Likewise.
* manual/errno.texi: Likewise.
* manual/filesys.texi: Likewise.
* manual/getopt.texi: Likewise.
* manual/job.texi: Likewise.
* manual/lang.texi: Likewise.
* manual/llio.texi: Likewise.
* manual/locale.texi: Likewise.
* manual/math.texi: Likewise.
* manual/memory.texi: Likewise.
* manual/message.texi: Likewise.
* manual/pattern.texi: Likewise.
* manual/pipe.texi: Likewise.
* manual/process.texi: Likewise.
* manual/resource.texi: Likewise.
* manual/search.texi: Likewise.
* manual/setjmp.texi: Likewise.
* manual/signal.texi: Likewise.
* manual/socket.texi: Likewise.
* manual/startup.texi: Likewise.
* manual/stdio.texi: Likewise.
* manual/string.texi: Likewise.
* manual/sysinfo.texi: Likewise.
* manual/syslog.texi: Likewise.
* manual/terminal.texi: Likewise.
* manual/threads.texi: Likewise.
* manual/time.texi: Likewise.
* manual/users.texi: Likewise.
Header and standards annotations are slated for standardization,
including being rendered in the description of functions, variables,
etc. (elements), and eventually required. This commit adds @standards
dummy macros so we can convert all existing annotations to the new
framework while maintaining the rendered status quo.
There needs to be a way to disambiguate annotations in lists of @*x
elements, where a common description is shared but some elements may
have different headers or standards. The @standardsx macro fills this
role by accepting an additional parameter: the name of the annotated
element.
* manual/macros.texi (@standards): New macro. Provide
placeholder for header and standards annotations.
(@standardsx): New macro. Likewise, for lists of @*x
elements.
The @errno macro is extended to render the canonical error string in
every documented errno error. Redundant entries and "???" are
removed. Sixty-six errors now at least contain the error string as
the description, where no description (or "???") existed before.
* manual/errno.texi: Remove redundant error strings.
* manual/macros.texi (@errno): Render the error string in
every description.
errno.texi documents error macros, their values, and error strings in
Texinfo @comments, some of which are also used for @standards. The
purpose of this commit is to separate the standards from the error
strings so that both the @standards conversion script picks up clean
@standards and the errno documentation framework is improved.
The error names, values, and messages are consolidated in a new custom
macro, @errno. It is not clear that scripts within the sources rely
on the special Texinfo @comment-based format to generate files used
throughout the library, so the definition of @errno in macros.texi now
provides a comment indicating the dependency. The dependent scripts
are updated to use @errno, which also simplifies them a bit. The
files those scripts generate were verified to be unchanged.
The @errno macro is not visibly rendered in any way at this time, but
it does use an @cindex command to add the error string to the Concept
Index, to facilitate searching on error messages.
* manual/errno.texi: Convert @comment-based errno
documentation to @errno.
* manual/macros.texi (@errno): New macro. Consolidate errors,
their values, and messages, adding the error string to the
Concept Index. Provide a warning in the comment about
external (to the manual) dependencies.
* sysdeps/gnu/errlist.awk: Use @errno instead of @comments.
* sysdeps/mach/hurd/errnos.awk: Likewise.
Rical Jasan
Ondřej Bílka
Alexandre Oliva
Joseph Myers