Page MenuHomeFreeBSD
Files F133166812

D17114.id47894.diff
No OneTemporary
Actions

D17114.id47894.diff
View Options

Index: en_US.ISO8859-1/articles/Makefile
===================================================================
--- en_US.ISO8859-1/articles/Makefile
+++ en_US.ISO8859-1/articles/Makefile
@@ -22,6 +22,8 @@
SUBDIR+= linux-emulation
SUBDIR+= linux-users
SUBDIR+= mailing-list-faq
+SUBDIR+= manpage-howto
+SUBDIR+= mh
SUBDIR+= nanobsd
SUBDIR+= new-users
SUBDIR+= pam
Index: en_US.ISO8859-1/articles/manpage-howto/Makefile
===================================================================
--- en_US.ISO8859-1/articles/manpage-howto/Makefile
+++ en_US.ISO8859-1/articles/manpage-howto/Makefile
@@ -0,0 +1,18 @@
+#
+# $FreeBSD$
+#
+# Article: How to write a man page.
+#
+
+DOC?= article
+
+FORMATS?= html
+WITH_ARTICLE_TOC?= YES
+
+INSTALL_COMPRESSED?=gz
+INSTALL_ONLY_COMPRESSED?=
+
+SRCS= article.sgml
+
+DOC_PREFIX?= ${.CURDIR}/../../..
+.include "${DOC_PREFIX}/share/mk/doc.project.mk"
Index: en_US.ISO8859-1/articles/manpage-howto/article.sgml
===================================================================
--- en_US.ISO8859-1/articles/manpage-howto/article.sgml
+++ en_US.ISO8859-1/articles/manpage-howto/article.sgml
@@ -0,0 +1,443 @@
+<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [
+<!ENTITY % articles.ent PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Articles Entity Set//EN">
+%articles.ent;
+]>
+
+<article>
+ <articleinfo>
+ <title>Creating a Manual Page from Scratch</title>
+
+ <author>
+ <firstname>Joe</firstname>
+ <surname>Barbish</surname>
+ <affiliation>
+ <address><email>fbsd1@a1poweruser.com</email></address>
+ </affiliation>
+ <contrib>Original article by</contrib>
+ </author>
+
+ <author>
+ <firstname>Niclas</firstname>
+ <surname>Zeising</surname>
+ <affiliation>
+ <address><email>zeising@FreeBSD.org</email></address>
+ </affiliation>
+ <contrib>Rewritten and SGML marked up by</contrib>
+ </author>
+
+ <pubdate>$FreeBSD$</pubdate>
+
+ <copyright>
+ <year>2011</year>
+ <holder role="mailto:fbsd1@a1poweruser.com">Joe Barbish</holder>
+ </copyright>
+
+ <copyright>
+ <year>2011</year>
+ <year>2012</year>
+ <holder role="mailto:zeising@FreeBSD.org">Niclas Zeising</holder>
+ </copyright>
+
+ <abstract>
+ <para>Manual pages are the most common way of documenting applications,
+ <acronym role="Application Programming Interface">API</acronym>s
+ and other important aspects of &os;. The manual pages are available
+ using the &man.man.1; command. This article gives a slightly more
+ in-depth explanation of manual pages and how a manual page is
+ written using the &man.groff.mdoc.7; macro language.</para>
+ </abstract>
+ </articleinfo>
+
+ <sect1>
+ <title>What is a Manual Page?</title>
+ <para> The &os; documentation manual system is comprised on many
+ manuals that are intended to be displayed using the &man.man.1;
+ command. The &os; base system have an extensive set of manuals
+ covering everything from kernel interfaces and library
+ <acronym role="Application Programming Interface">API</acronym>s
+ to descriptions and instructions on how to use different commands
+ and applications, configuration files and much more. Most ports
+ also install manual pages which can be accessed in the same way.</para>
+
+ <para>The &os; manual system divides the manual into 9 sections:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Section 1: FreeBSD General Commands Manual</para>
+ </listitem>
+ <listitem>
+ <para>Section 2: FreeBSD System Calls Manual</para>
+ </listitem>
+ <listitem>
+ <para>Section 3: FreeBSD Library Functions Manual</para>
+ </listitem>
+ <listitem>
+ <para>Section 4: FreeBSD Kernel Interfaces Manual</para>
+ </listitem>
+ <listitem>
+ <para>Section 5: FreeBSD File Formats Manual</para>
+ </listitem>
+ <listitem>
+ <para>Section 6: FreeBSD Games Manual</para>
+ </listitem>
+ <listitem>
+ <para>Section 7: FreeBSD Miscellaneous Information Manual</para>
+ </listitem>
+ <listitem>
+ <para>Section 8: FreeBSD System Manager's Manual</para>
+ </listitem>
+ <listitem>
+ <para>Section 9: FreeBSD Kernel Developer's Manual</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>The layout is standardized and the &man.groff.mdoc.7;
+ documentation macro markup language is used to format manuals.
+ The files containing the source
+ for each manual are located in the
+ <filename class="directory"> /usr/share/man/man<replaceable>N</replaceable>/</filename>
+ directory tree, where <replaceable>N</replaceable> is one of the
+ following sections.</para>
+ <para>Manual pages are named after the command, function, or similar they
+ describe. This name is then suffixed with
+ <literal>.<replaceable>X</replaceable></literal> denoting which section
+ the manual belongs to. When manual pages are installed on a system they
+ are usually compressed using <application>gzip</application> to save
+ harddrive space, and the compression adds the file extension
+ <literal>.gz</literal>. When viewing a manual page using
+ <application>man</application> it is automatically uncompressed. As an
+ example, a manual page for <application>mv</application> belonging to
+ section 1 would be named <filename>mv.1</filename>. If it is compressed
+ using <application>gzip</application> the file name would instead be
+ <filename>mv.1.gz</filename>.</para>
+
+ <para>The file itself is a text file marked up using the
+ <literal>mdoc</literal> macro package for &man.troff.1;. More detailed
+ information is also available in &man.groff.mdoc.7;.</para>
+ </sect1>
+
+ <sect1>
+ <title>Creating the Manual Source File</title>
+ <para>There are example manual pages in
+ <filename role="directory">share/examples/mdoc/</filename> to use as
+ templates. It is also possible to copy an existing manual page and use
+ that as a starting point. If the copied manual page is compressed, it
+ can be uncompressed using <application>gunzip</application>. Once the
+ manual page tamplate has been aquired it can be edited.</para>
+
+ <para>In the beginning of the manual page there is the usual copyright
+ notice. This notice will not be shown in the output when using
+ <application>man</application> because it is commented, which is
+ acomplished by prepending each line with <literal>.\"</literal>. All
+ &man.groff.mdoc.7; macros begin with a <literal>.</literal> followed
+ by an uppercase and a lower case letter. These macros are used to format
+ the manual page in the appropriate manner. A list of all macros can be
+ found in &man.groff.mdoc.7;.</para>
+
+ <para>After the copyright section the actual manual page begins. It is
+ customary to have the date of the last edit as well as macros with
+ the manual page name and section and a short description of what the
+ utility is used for. It can look something like this:</para>
+
+ <programlisting>.Dd October 10, 2011 <co id="co-man-dd">
+.Dt EXAMPLE 1 <co id="co-man-dt">
+.Os <co id="co-man-os">
+.Sh NAME <co id="co-man-sh">
+.Nm example <co id="co-man-nm">
+.Nd example manual page <co id="co-man-nd"></programlisting>
+
+ <calloutlist>
+ <callout arearefs="co-man-dd">
+ <para>This line, that starts with
+ <literal>.Dd</literal> is the document date. This should correspond
+ to the last time the manual was changed and will be displayed at
+ the bottom of the rendered manual.</para>
+ </callout>
+
+ <callout arearefs="co-man-dt">
+ <para>The next line contains the <literal>.Dt</literal> macro followed
+ by the name and section of the document, in capitals. This is will
+ then be showed in the upper corners when the manual is viewed.</para>
+ </callout>
+
+ <callout arearefs="co-man-os">
+ <para>This line makes the operating system and version print at the
+ bottom of the page.</para>
+ </callout>
+
+ <callout arearefs="co-man-sh">
+ <para>The <literal>.Sh</literal> macro indicates a headline for the
+ start of a new section. It is followed by the name of the section.
+ A manual page usually have a defined set of sections and the order
+ in which they come. This depends on what is being documented, and
+ will be explained in more detail in [REFERENCE].</para>
+ </callout>
+
+ <callout arearefs="co-man-nm">
+ <para>The first section of the manual contains <literal>.Nm</literal>
+ followed by the name of the manual page. This macro can then be
+ used without any trailing text and it will be replaced by the name.</para>
+ </callout>
+
+ <callout arearefs="co-man-nd">
+ <para>This line contains a one line description of what is being
+ being documented.</para>
+ </calloutlist>
+
+ <para>When writing a manual page it is good to check how it renders with
+ the &man.man.1; command. By default, &man.man.1; looks in
+ <filename role="directory">/usr/share/man</filename> and
+ <filename role="direcotry">/usr/local/share/man</filename> for the manual
+ so just typing <literal>man <replaceable>example</replaceable></literal>
+ will not work. To view a manual outside these paths it is necessary to
+ provide the path to the file in question. If it is located in the current
+ working directory, this will look something like this:</para>
+
+ <screen>&prompt.user; <userinput>man <replaceable>./example.1</replaceable></userinput></screen>
+
+ <para>With the example above, the rendered manual should display something
+ like the below. The date and version number might be different, and some
+ text might be bold or extra bright, depending on your terminal type.</para>
+
+ <programlisting>EXAMPLE(1) FreeBSD General Commands Manual EXAMPLE(1)
+
+NAME
+ example -- example manual page
+
+FreeBSD 9.0 October 10, 2011 FreeBSD 9.0</programlisting>
+
+ <para>It is also possible to use <application>groff</application> to render
+ the manual as pure ascii text. This way syntax errors, together with the
+ line of where they occur will be displayed. To do this, run:</para>
+
+ <screen>&prompt.user; <userinput>groff -mdoc -Tascii <replaceable>example.1</replaceable></userinput></screen>
+
+ <para>The next section is usually the synopsis, which is intended to give
+ an overwiev of what is documented. It is customary to list the arguments
+ of an application here, or the function names and arguments, if an
+ <acronym role="Application Programming Interface">API</acronym> is being
+ described. The &man.groff.mdoc.7; syntax for describing application
+ arguments and function signatures vary quite a lot, so the explanation
+ for how to write the synopsis section is split into two parts, with the
+ first explaining how to write an application manual and the second
+ explaining how to write an
+ <acronym role="Application Programming Interface">API</acronym> or
+ function manual.</para>
+
+ <para>In almost all cases, an application takes a variety of mandatory and
+ optional arguments, some of them mutually exclusive. There are a number
+ of macros to accomplish this:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>The <literal>.Fl</literal> macro is used mark up mandatory
+ arguments. For instance, <literal>.Fl c</literal> will render output
+ similar to <literal>-c</literal>. This macro can be combined with
+ <literal>.Ar</literal> to add an additional argument that
+ <literal>-c</literal> makes use of.</para>
+ </listitem>
+ <listitem>
+ <para>The <literal>.Op</literal> macro is used to mark up optional
+ arguments. It has to be combined with other macros to create the
+ actual argument list. <literal>.Op Fl b</literal> will make the
+ rendered output look like <literal>[-b]</literal>. Optional arguments
+ are usually rendered between bracets.</para>
+ </listitem>
+ <listitem>
+ <para>The <literal>.Ar</literal> argument can be used by itself to
+ denote arguments that does not have the initial <literal>-</literal>,
+ such as file name arguments.</para>
+ </listitem>
+ <listitem>
+ <para> The <literal>.Oo</literal> and <literal>.Oc</literal> macros can
+ be used to create a opening and closing bracet, respectively.</para>
+ </listitem>
+ <listitem>
+ <para>While not a macro, the pipe character, <literal>|</literal>, is
+ used to separate mutually exclusive arguments.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>This might seem a little complex at first, so to better illustrate how
+ it works, consider this example:</para>
+
+ <programlisting>.Sh SYNOPSIS
+.Nm
+.Op Fl a | b
+.Fl c Ar conf_file
+.Op Fl def
+.Ar bar_arg</programlisting>
+
+ <para>This example makes the rendered manual page look something like what
+ is shown below. Note in the example that several &man.groff.mdoc.7;
+ macros can be combined to create the desired output, and that only the
+ first macro on the line has the leading <literal>.</literal>.</para>
+
+ <programlisting>SYNOPSIS
+ example [-a | -b] -c conf_file [-def] bar_arg</programlisting>
+
+ <para>To instead document an
+ <acronym role="Application Programming Interface">API</acronym>, there is
+ a different set of macros to use to list the function signatures in the
+ synopsis. Sometimes when the function is part of a library, a library
+ section is added before the synopsis section. The library is then denoted
+ with the <literal>.Lb</literal> macro, like this;
+ <literal>.Lb libc</literal>, if the function is part of libc. The macros
+ to render a function signature listing are:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>The <literal>.In</literal> is used to mark files that needs to be
+ includeded in the source file, for C/C++ source.</para>
+ </listitem>
+ <listitem>
+ <para>The <literal>.Ft</literal> macro is used to note the return type
+ of the function.</para>
+ </listitem>
+ <listitem>
+ <para>The <literal>.Fn</literal> macro, followed by the function name
+ will list the actual function. Arguments to the function, if any,
+ should follow next, enclosed in double quoutes (<literal>"</literal>)
+ .</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>While not as complex as for the application argument list, it might
+ be a little overwhelming at first. The next example will hopefully
+ clarify:</para>
+
+ <programlisting>.Sh SYNOPSIS
+.In example.h
+.Ft char *
+.Fn example "int foo" "size_t bar" "char * baz"</programlisting>
+
+ <para>This example makes the rendered manpage look like what is shown below.
+ All macros can exist multiple times to denote more than one include file
+ and function, respectively.</para>
+
+ <programlisting>SYNOPSIS
+ #include &lt;example.h&gt;
+
+ char *
+ example(int foo, size_t bar, char * baz);</programlisting>
+
+ <para>After the synopsis comes the description section. This section, as
+ the name implies, contains the description of the application or
+ <acronym role="Application Programming Interface">API</acronym>. It is a
+ good idea to start with a short general description, if it is needed,
+ before starting to describe the different arguments or functions. To make
+ the manual page easy to read it is recommended to put the application
+ arguments into a list. This is acomplishded using the following
+ macros:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>The <literal>.Bl</literal> macro is used to begin a list. It can
+ take arguments to specify formatting and indentation, such as
+ <literal>-tag -width flag</literal>, which is used to indent the list
+ for use as a list of application arguments.</para>
+ </listitem>
+ <listitem>
+ <para>The <literal>.It</literal> macro is used for each item in the
+ list.</para>
+ </listitem>
+ <listitem>
+ <para>The <literal>.El</literal> macro is used to end the list.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>The macros described in the previous section about synopsis can still
+ be used to mark up different application arguments. These macros,
+ together with the list macros is then used to enumerate all macros and
+ describe them. As an example, consider the example below:</para>
+
+ <programlisting>.Sh DESCRIPTION
+The
+.Nm
+command is used to exemplify how to write a manual page.
+.Pp
+.Bl -tag -width flag
+.It Fl a
+A example argument that does nothing.
+.It Fl b
+Another example argument.
+A second sentence with further explanation.
+This can be used together with
+.Fl d
+to create a nice effect.
+.It Fl c
+Use the configuration file
+.Ar conf_file
+instead of the default.
+.It Ar bar_arg
+Another argument.
+.El</programlisting>
+
+ <para>As can be seen, this example makes use of several macros previously
+ described, such as <literal>.Fl</literal> and <literal>.Ar</literal>. It
+ is also important to note that whenever a reference to the application
+ name is done, the <literal>.Nm</literal> macro is used. This way, if the
+ application has a name change, only the <literal>.Nm</literal> macro in
+ the beginning of the manual has to be changed. When viewing the above
+ using &man.man.1; it will look something like this:</para>
+
+ <programlisting>DESCRIPTION
+ The example command is used to exemplify how to write a manual page.
+
+ -a A example argument that does nothing.
+
+ -b Another example argument. A second sentence with further explana-
+ tion. This can be used together with -d to create a nice effect.
+
+ -c Use the configuration file conf_file instead of the default.
+
+ bar_arg
+ Another argument.</programlisting>
+
+ <para>When describing an
+ <acronym role="Application Programming Interface">API</acronym>
+ there is no need for an argument list, the same way as for an
+ application. Instead, all functions that the manual covers
+ should be described, together with their arguments. As in the
+ synopsis section, <literal>.Fn</literal> is used to mark a function
+ and the <literal>.Fa</literal> macro is used for function arguments.
+ To illustrate, consider the following:</para>
+ <programlisting>.Sh DESCRIPTION
+The
+.Fn example
+fucntion is an example.
+An integer is passed in
+.Fa foo
+and
+.Fa bar
+is used to demonstrate a second argument.
+A string is passed in
+.Fa baz .</programlisting>
+
+ <para>This produces the following when viewed with &man.man.1;:</para>
+
+ <programlisting>DESCRIPTION
+ The example() fucntion is an example. An integer is passed in foo and
+ bar is used to demonstrate a second argument. A string is passed in baz.</programlisting>
+
+ <para>To add more sections, just contintue using <literal>.Sh</literal>
+ for each new section heading. Sometimes it is good to have a
+ section with examples or a section with comaptibility notes. If an
+ application uses files it is good practice to include a
+ <literal>FILES</literal> section, listing all files in a list, using
+ <literal>.Bl</literal> and <literal>.It</literal> macros the same way
+ as in the <literal>DESCRIPTION</literal> section. In a
+ <literal>SEE ALSO</literal> section cross references can be added. To
+ cross reference another manual, use <literal>.Xr</literal> followed by the
+ name and the section.</para>
+
+ <programlisting>.Xr man 1</programlisting>
+
+ <para>creates a cross reference to &man.man.1;. It is also possible to
+ add an <literal>AUTHORS</literal> section detailing who wrote the program
+ or <acronym>API</acronym> and manual, or a <literal>HISTORY</literal>
+ section. See existing manuals for more examples of sections and what
+ they are used for.</para>
+
+ </sect1>
+</article>
Index: en_US.ISO8859-1/books/porters-handbook/uses/chapter.xml
===================================================================
--- en_US.ISO8859-1/books/porters-handbook/uses/chapter.xml
+++ en_US.ISO8859-1/books/porters-handbook/uses/chapter.xml
@@ -689,6 +689,43 @@
build- and run-time dependencies.</para>
</sect1>
+ <sect1 xml:id="uses-gl">
+ <title><literal>gl</literal></title>
+
+ <para>Possible arguments: (none)</para>
+
+ <para>Provides an easy way to depend on
+ <application>GL</application> components. The components
+ should be listed in <varname>USE_GL</varname>. The available
+ components are:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><literal>egl</literal></para>
+ </listitem>
+
+ <listitem>
+ <para><literal>gl</literal></para>
+ </listitem>
+
+ <listitem>
+ <para><literal>glesv2</literal></para>
+ </listitem>
+
+ <listitem>
+ <para><literal>glu</literal></para>
+ </listitem>
+
+ <listitem>
+ <para><literal>glut</literal></para>
+ </listitem>
+
+ <listitem>
+ <para><literal>glw</literal></para>
+ </listitem>
+ </itemizedlist>
+ </sect1>
+
<sect1 xml:id="uses-gmake">
<title><literal>gmake</literal></title>

File Metadata

Mime Type
text/plain
Expires
Fri, Oct 24, 2:24 PM (15 h, 49 m)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
24134778
Default Alt Text
D17114.id47894.diff (21 KB)

Event Timeline