Man-Page-Generation.html 6.2 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132
  1. <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
  2. <html>
  3. <!-- Copyright (C) 1988-2017 Free Software Foundation, Inc.
  4. Permission is granted to copy, distribute and/or modify this document
  5. under the terms of the GNU Free Documentation License, Version 1.3 or
  6. any later version published by the Free Software Foundation; with the
  7. Invariant Sections being "Funding Free Software", the Front-Cover
  8. Texts being (a) (see below), and with the Back-Cover Texts being (b)
  9. (see below). A copy of the license is included in the section entitled
  10. "GNU Free Documentation License".
  11. (a) The FSF's Front-Cover Text is:
  12. A GNU Manual
  13. (b) The FSF's Back-Cover Text is:
  14. You have freedom to copy and modify this GNU Manual, like GNU
  15. software. Copies published by the Free Software Foundation raise
  16. funds for GNU development. -->
  17. <!-- Created by GNU Texinfo 5.2, http://www.gnu.org/software/texinfo/ -->
  18. <head>
  19. <title>GNU Compiler Collection (GCC) Internals: Man Page Generation</title>
  20. <meta name="description" content="GNU Compiler Collection (GCC) Internals: Man Page Generation">
  21. <meta name="keywords" content="GNU Compiler Collection (GCC) Internals: Man Page Generation">
  22. <meta name="resource-type" content="document">
  23. <meta name="distribution" content="global">
  24. <meta name="Generator" content="makeinfo">
  25. <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
  26. <link href="index.html#Top" rel="start" title="Top">
  27. <link href="Option-Index.html#Option-Index" rel="index" title="Option Index">
  28. <link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
  29. <link href="Documentation.html#Documentation" rel="up" title="Documentation">
  30. <link href="Miscellaneous-Docs.html#Miscellaneous-Docs" rel="next" title="Miscellaneous Docs">
  31. <link href="Texinfo-Manuals.html#Texinfo-Manuals" rel="prev" title="Texinfo Manuals">
  32. <style type="text/css">
  33. <!--
  34. a.summary-letter {text-decoration: none}
  35. blockquote.smallquotation {font-size: smaller}
  36. div.display {margin-left: 3.2em}
  37. div.example {margin-left: 3.2em}
  38. div.indentedblock {margin-left: 3.2em}
  39. div.lisp {margin-left: 3.2em}
  40. div.smalldisplay {margin-left: 3.2em}
  41. div.smallexample {margin-left: 3.2em}
  42. div.smallindentedblock {margin-left: 3.2em; font-size: smaller}
  43. div.smalllisp {margin-left: 3.2em}
  44. kbd {font-style:oblique}
  45. pre.display {font-family: inherit}
  46. pre.format {font-family: inherit}
  47. pre.menu-comment {font-family: serif}
  48. pre.menu-preformatted {font-family: serif}
  49. pre.smalldisplay {font-family: inherit; font-size: smaller}
  50. pre.smallexample {font-size: smaller}
  51. pre.smallformat {font-family: inherit; font-size: smaller}
  52. pre.smalllisp {font-size: smaller}
  53. span.nocodebreak {white-space:nowrap}
  54. span.nolinebreak {white-space:nowrap}
  55. span.roman {font-family:serif; font-weight:normal}
  56. span.sansserif {font-family:sans-serif; font-weight:normal}
  57. ul.no-bullet {list-style: none}
  58. -->
  59. </style>
  60. </head>
  61. <body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
  62. <a name="Man-Page-Generation"></a>
  63. <div class="header">
  64. <p>
  65. Next: <a href="Miscellaneous-Docs.html#Miscellaneous-Docs" accesskey="n" rel="next">Miscellaneous Docs</a>, Previous: <a href="Texinfo-Manuals.html#Texinfo-Manuals" accesskey="p" rel="prev">Texinfo Manuals</a>, Up: <a href="Documentation.html#Documentation" accesskey="u" rel="up">Documentation</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Option-Index.html#Option-Index" title="Index" rel="index">Index</a>]</p>
  66. </div>
  67. <hr>
  68. <a name="Man-Page-Generation-1"></a>
  69. <h4 class="subsubsection">6.3.7.2 Man Page Generation</h4>
  70. <p>Because of user demand, in addition to full Texinfo manuals, man pages
  71. are provided which contain extracts from those manuals. These man
  72. pages are generated from the Texinfo manuals using
  73. <samp>contrib/texi2pod.pl</samp> and <code>pod2man</code>. (The man page for
  74. <code>g++</code>, <samp>cp/g++.1</samp>, just contains a &lsquo;<samp>.so</samp>&rsquo; reference
  75. to <samp>gcc.1</samp>, but all the other man pages are generated from
  76. Texinfo manuals.)
  77. </p>
  78. <p>Because many systems may not have the necessary tools installed to
  79. generate the man pages, they are only generated if the
  80. <samp>configure</samp> script detects that recent enough tools are
  81. installed, and the Makefiles allow generating man pages to fail
  82. without aborting the build. Man pages are also included in release
  83. distributions. They are generated in the source directory.
  84. </p>
  85. <p>Magic comments in Texinfo files starting &lsquo;<samp>@c man</samp>&rsquo; control what
  86. parts of a Texinfo file go into a man page. Only a subset of Texinfo
  87. is supported by <samp>texi2pod.pl</samp>, and it may be necessary to add
  88. support for more Texinfo features to this script when generating new
  89. man pages. To improve the man page output, some special Texinfo
  90. macros are provided in <samp>doc/include/gcc-common.texi</samp> which
  91. <samp>texi2pod.pl</samp> understands:
  92. </p>
  93. <dl compact="compact">
  94. <dt><code>@gcctabopt</code></dt>
  95. <dd><p>Use in the form &lsquo;<samp>@table @gcctabopt</samp>&rsquo; for tables of options,
  96. where for printed output the effect of &lsquo;<samp>@code</samp>&rsquo; is better than
  97. that of &lsquo;<samp>@option</samp>&rsquo; but for man page output a different effect is
  98. wanted.
  99. </p></dd>
  100. <dt><code>@gccoptlist</code></dt>
  101. <dd><p>Use for summary lists of options in manuals.
  102. </p></dd>
  103. <dt><code>@gol</code></dt>
  104. <dd><p>Use at the end of each line inside &lsquo;<samp>@gccoptlist</samp>&rsquo;. This is
  105. necessary to avoid problems with differences in how the
  106. &lsquo;<samp>@gccoptlist</samp>&rsquo; macro is handled by different Texinfo formatters.
  107. </p></dd>
  108. </dl>
  109. <p>FIXME: describe the <samp>texi2pod.pl</samp> input language and magic
  110. comments in more detail.
  111. </p>
  112. <hr>
  113. <div class="header">
  114. <p>
  115. Next: <a href="Miscellaneous-Docs.html#Miscellaneous-Docs" accesskey="n" rel="next">Miscellaneous Docs</a>, Previous: <a href="Texinfo-Manuals.html#Texinfo-Manuals" accesskey="p" rel="prev">Texinfo Manuals</a>, Up: <a href="Documentation.html#Documentation" accesskey="u" rel="up">Documentation</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Option-Index.html#Option-Index" title="Index" rel="index">Index</a>]</p>
  116. </div>
  117. </body>
  118. </html>