* Document eblank and eqawarn in the ebuild.5 man page.

* Create "Ebuild Helper Functions" section docbook format,
  including all the functions documented in the ebuild.5
  man page.

svn path=/main/trunk/; revision=10687

diff --git a/doc/package/ebuild.docbook b/doc/package/ebuild.docbook
index 5466f99db38669a5fa8bcb9907b78221bec7de52..4bdb8129d92bb8cc08456f5ecbb951960194b144 100644 (file)
--- a/doc/package/ebuild.docbook
+++ b/doc/package/ebuild.docbook
@@ -1,4 +1,5 @@
 <chapter id='package-ebuild'>
 <title>Ebuild</title>
 &package_ebuild_phases;
+&package_ebuild_helper_functions;
 </chapter>

diff --git a/doc/package/ebuild/helper_functions.docbook b/doc/package/ebuild/helper_functions.docbook
new file mode 100644 (file)
index 0000000..ab83d4e
--- /dev/null
+++ b/doc/package/ebuild/helper_functions.docbook
@@ -0,0 +1,57 @@
+<sect1 id='package-ebuild-helper-functions'>
+       <title>Helper Functions</title>
+       <sect2 id='package-ebuild-helper-functions-output'>
+       <title>Output</title>
+       <sect3 id='package-ebuild-helper-functions-output-ebegin'>
+       <title>ebegin</title>
+       <para>
+       Like einfo, we output a helpful message and then hint that the following
+       operation may take some time to complete. Once the task is finished, you
+       need to call eend.
+       </para>
+       </sect3>
+       <sect3 id='package-ebuild-helper-functions-output-eblank'>
+       <title>eblank</title>
+       <para>
+       Show a blank line. Consecutive eblank calls collapse into
+       a single blank line.
+       </para>
+       </sect3>
+       <sect3 id='package-ebuild-helper-functions-output-eend'>
+       <title>eend</title>
+       <para>
+       Followup the ebegin message with an appropriate "OK" or "!!" (for errors)
+       marker. If status is non-zero, then the additional error message is
+       displayed.
+       </para>
+       </sect3>
+       <sect3 id='package-ebuild-helper-functions-output-einfo'>
+       <title>einfo</title>
+       <para>
+       Same as elog, but should be used when the message isn't important
+       to the user (like progress or status messages during the build process).
+       </para>
+       </sect3>
+       <sect3 id='package-ebuild-helper-functions-output-elog'>
+       <title>elog</title>
+       <para>
+       If you need to display a message that you wish the user to read
+       and take notice of, then use elog. It works just like echo(1),
+       but adds a little more to the output so as to catch the user's eye.
+       The message will also be logged by portage for later review.
+       </para>
+       </sect3>
+       <sect3 id='package-ebuild-helper-functions-output-eqawarn'>
+       <title>eqawarn</title>
+       <para>
+       Same as einfo, but should be used when showing a QA warning to the user.
+       </para>
+       </sect3>
+       <sect3 id='package-ebuild-helper-functions-output-ewarn'>
+       <title>ewarn</title>
+       <para>
+       Same as einfo, but should be used when showing a warning to the user.
+       </para>
+       </sect3>
+       </sect2>
+</sect1>

diff --git a/doc/portage.docbook b/doc/portage.docbook
index d158c1a2195e29cf8b8ab349620a4f29b6a4d47a..8c29303e66c0d5898dfd4f99a5a7b8d8c602ece6 100644 (file)
--- a/doc/portage.docbook
+++ b/doc/portage.docbook
@@ -14,6 +14,7 @@
        <!ENTITY package SYSTEM "package.docbook">
        <!ENTITY package_ebuild SYSTEM "package/ebuild.docbook">
        <!ENTITY package_ebuild_phases SYSTEM "package/ebuild/phases.docbook">
+       <!ENTITY package_ebuild_helper_functions SYSTEM "package/ebuild/helper_functions.docbook">
        <!ENTITY qa SYSTEM "qa.docbook">
        <!ENTITY config SYSTEM "config.docbook">
        <!ENTITY config_bashrc SYSTEM "config/bashrc.docbook">

diff --git a/man/ebuild.5 b/man/ebuild.5
index 9885175ccc39a56f6689919be24f65a380d29bd0..7d544a75d547da297740c4bfae97bcb84a293898 100644 (file)
--- a/man/ebuild.5
+++ b/man/ebuild.5
@@ -580,6 +580,10 @@ VERINS="$(best_version net\-ftp/glftpd)"
 .RE
 .SH "HELPER FUNCTIONS: OUTPUT"
 .TP
+\fBeblank\fR
+Show a blank line. Consecutive eblank calls collapse into
+a single blank line.
+.TP
 \fBeinfo\fR \fI"disposable message"\fR
 Same as \fBelog\fR, but should be used when the message isn't important to the
 user (like progress or status messages during the build process).
@@ -593,6 +597,9 @@ will also be logged by portage for later review.
 \fBewarn\fR \fI"warning message"\fR
 Same as \fBeinfo\fR, but should be used when showing a warning to the user.
 .TP
+\fBeqawarn\fR \fI"QA warning message"\fR
+Same as \fBeinfo\fR, but should be used when showing a QA warning to the user.
+.TP
 \fBeerror\fR \fI"error message"\fR
 Same as \fBeinfo\fR, but should be used when showing an error to the user.
 .TP