Hi! Small ping.
Let me know if you are interested in this kind of docu cleanup.
Best regards,
Em 2026-05-19 00:24, Léo Hardt escreveu:
Good evening!
This is a small patch for a 'FIXME' inside the Internals
manual from 0a553c7. One could enter into arbitrary detail
about what texi2pod handles, s.a. variables, '@setfilename',
etc., but it seemed counterproductive to list all behaviours.
For that one could see the file themselves.
It also seems that the magic comment '@c man title' has the
same effect as '@settitle', and may only be useful when the
intention is to have the 'man' and PDF/HTML titles distinct.
This is now used only by the Algol68, D, and Go front-end docs.
I'm not sure it's worthy to document that feature, even though
it is a magic comment exclusive to texi2pod.
Let me know if you disagree.
Best regards,
Léo
gcc/ChangeLog:
* doc/sourcebuild.texi: Document texi2pod magic comments.
Signed-off-by: Léo Hardt <[email protected]>
---
gcc/doc/sourcebuild.texi | 21 +++++++++++----------
1 file changed, 11 insertions(+), 10 deletions(-)
diff --git a/gcc/doc/sourcebuild.texi b/gcc/doc/sourcebuild.texi
index 6badae4f7..390f44520 100644
--- a/gcc/doc/sourcebuild.texi
+++ b/gcc/doc/sourcebuild.texi
@@ -459,13 +459,17 @@ installed, and the Makefiles allow generating man
pages to fail
without aborting the build. Man pages are also included in release
distributions. They are generated in the source directory.
-Magic comments in Texinfo files starting @samp{@@c man} control what
-parts of a Texinfo file go into a man page. Only a subset of Texinfo
-is supported by @file{texi2pod.pl}, and it may be necessary to add
-support for more Texinfo features to this script when generating new
-man pages. To improve the man page output, some special Texinfo
-macros are provided in @file{doc/include/gcc-common.texi} which
-@file{texi2pod.pl} understands:
+Man page sections are started by using a Magic comment
+@samp{@@c man begin SECTION_NAME} and ended by @samp{@@c man end}.
+The order of sections produced is defined in @file{texi2pod.pl}. Note
+that the @samp{SEE ALSO} section is named @samp{SEEALSO} in the Magic
+comments.
+
+Only a subset of Texinfo is supported by @file{texi2pod.pl}, and it
+may be necessary to add support for more Texinfo features to this
+script when generating new man pages. To improve the man page output,
+some special Texinfo macros are provided in
+@file{doc/include/gcc-common.texi} which @file{texi2pod.pl} understands:
@table @code
@item @@gcctabopt
@@ -477,9 +481,6 @@ wanted.
Use for summary lists of options in manuals.
@end table
-FIXME: describe the @file{texi2pod.pl} input language and magic
-comments in more detail.
-
@node Miscellaneous Docs
@subsubsection Miscellaneous Documentation
--
2.39.5
