From c4dca75bd13ee75850d1f8628b3b1bae795064d2 Mon Sep 17 00:00:00 2001
From: Zac Medico <zmedico@gentoo.org>
Date: Tue, 17 Jun 2008 07:46:23 +0000
Subject: * 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
---
 doc/package/ebuild.docbook                  |  1 +
 doc/package/ebuild/helper_functions.docbook | 57 +++++++++++++++++++++++++++++
 2 files changed, 58 insertions(+)
 create mode 100644 doc/package/ebuild/helper_functions.docbook

(limited to 'doc/package')

diff --git a/doc/package/ebuild.docbook b/doc/package/ebuild.docbook
index 5466f99d..4bdb8129 100644
--- 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
index 00000000..ab83d4ed
--- /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>
-- 
cgit v1.2.3-65-gdbad