Sophie

Sophie

distrib > Mageia > 7 > i586 > media > core-release > by-pkgid > a47d51544ec63a4f57df69ffdfe2c320 > files > 23

aephea-10_008-8.mga7.noarch.rpm

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Copyright (c) 2010 Stijn van Dongen -->
<head>
<meta name="keywords" content="manual">
<style type="text/css">
/* START aephea.base.css */
body
{ text-align: justify;
margin-left: 0%;
margin-right: 0%;
}
a:link { text-decoration: none; }
a:active { text-decoration: none; }
a:visited { text-decoration: none; }
a:link { color: #1111aa; }
a:active { color: #1111aa; }
a:visited { color: #111166; }
a.local:link { color: #11aa11; }
a.local:active { color: #11aa11; }
a.local:visited { color: #116611; }
a.intern:link { color: #1111aa; }
a.intern:active { color: #1111aa; }
a.intern:visited { color: #111166; }
a.extern:link { color: #aa1111; }
a.extern:active { color: #aa1111; }
a.extern:visited { color: #661111; }
a.quiet:link { color: black; }
a.quiet:active { color: black; }
a.quiet:visited { color: black; }
div.verbatim
{ font-family: monospace;
margin-top: 1em;
margin-bottom: 1em;
font-size: 10pt;
margin-left: 2em;
white-space: pre;
}
div.indent
{ margin-left: 8%;
margin-right: 0%;
}
.right { text-align: right; }
.left { text-align: left; }
.nowrap { white-space: nowrap; }
.item_leader
{ position: relative;
margin-left: 8%;
}
.item_compact { position: absolute; vertical-align: baseline; }
.item_cascade { position: relative; }
.item_leftalign { text-align: left; }
.item_rightalign
{ width: 2em;
text-align: right;
}
.item_compact .item_rightalign
{ position: absolute;
width: 52em;
right: -2em;
text-align: right;
}
.item_text
{ position: relative;
margin-left: 3em;
}
.smallcaps { font-size: smaller; text-transform: uppercase }
/* END aephea.base.css */
.pink { background-color: pink; }
</style>
<title>The PUD faq mini-language FAQ</title>
</head>
<body>
<p style="text-align:right">
8 Jan 2010&nbsp;&nbsp;&nbsp;
<a class="local" href="pud-faq.ps"><b>pud-faq</b></a>
1.002, 10-008
</p>
<div class=" itemize " style="margin-top:1em; font-size:100%">
<div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-3em">1.</div></div>
<div class=" item_text " style="margin-left:4em">
<a class="intern" href="#name">NAME</a>
</div>
<div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-3em">2.</div></div>
<div class=" item_text " style="margin-left:4em">
<a class="intern" href="#description">DESCRIPTION</a>
</div>
<div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-3em">3.</div></div>
<div class=" item_text " style="margin-left:4em">
<a class="intern" href="#resources">RESOURCES</a>
</div>
<div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-3em">4.</div></div>
<div class=" item_text " style="margin-left:4em">
<a class="intern" href="#toc">TOC</a>
</div>
<div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-3em">5.</div></div>
<div class=" item_text " style="margin-left:4em">
<a class="intern" href="#faq">FAQ</a>
</div>
<div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-3em">6.</div></div>
<div class=" item_text " style="margin-left:4em">
<a class="intern" href="#author">AUTHOR</a>
</div>
<div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-3em">7.</div></div>
<div class=" item_text " style="margin-left:4em">
<a class="intern" href="#seealso">SEE ALSO</a>
</div>
</div>

<a name="name"></a>
<h2>NAME</h2>
<p style="margin-bottom:0" class="asd_par">
pud-faq &mdash; faqs and facts about the Portable Unix Documentation FAQ authoring language.</p>
<p style="margin-bottom:0" class="asd_par">
This document describes the Portable Unix Documentation (PUD) faq
mini-language in the style of a FAQ. PUD-faq is built on top of the
macro interpreter zoem. A PUD document is generally well-structured,
relatively free of formatting statements, compact to write and easily
extendable. It can be converted to both troff and html, for viewing in
terminals and browsers. High quality Postscript and plain text formats
can be derived from the troff output. Refer to <a class="local sibling" href="pud-man.html">pud-man</a>
for examples.</p>

<a name="description"></a>
<h2>DESCRIPTION</h2>
<p style="margin-top:0em; margin-bottom:0em">
The PUD faq macros extend the PUD manual macros; a PUD faq document
must import both man.zmm and faq.zmm. There are only a few additional
faq macros in faq.zmm. The overall layout of a faq document is as
follows:</p>
<div class="verbatim">
\import{man.zmm}
\import{faq.zmm}

\begin{pud::man}{
   {name}{pud-faq}
   {html_title}{The PUD faq mini-language FAQ}
   {author}{Stijn van Dongen}
   {section}{7}
}

\"faq::preamble"

\${html}{\"man::maketoc"}

\sec{toc}{TOC}
\"faq::maketoc"

\begin{faqsec}{{ref}{Labelx}{cap}{Captionx}}
   content
\end{faqsec}

\begin{faqsec}{{ref}{Labely}{cap}{Captiony}}
   content
\end{faqsec}

\end{pud::man}</div>
<p style="margin-bottom:0" class="asd_par">
The PUD manual macros are documented in the
<a class="local sibling" href="pud-man.html">pud-man</a> manual page.</p>
<p style="margin-bottom:0" class="asd_par">
Create your FAQ according to the lay-out above and as described further
below. Refer to <a class="intern" href="#q_real">Question&nbsp;2.3</a> for
full-size examples.</p>
<p style="margin-bottom:0" class="asd_par">
Once you have written your FAQ, process it as follows.</p>
<div class="verbatim">   zoem -i your-faq.azm -d html
   zoem -i your-faq.azm -d html
   zoem -i your-faq.azm -d roff -o your-faq.7
   zoem -i your-faq.azm -d roff -o your-faq.7</div>
<p style="margin-top:0em; margin-bottom:0em">
This generates files your-faq.html and your-faq.7.
Each device is run twice to be certain that references
are found and linked.</p>

<a name="resources"></a>
<h2>RESOURCES</h2>
<div class=" itemize " style="margin-top:1em; font-size:100%">
<div class=" item_compact"><div class=" item_rightalign " style="right:-1em"><span class="itembullet">&bull;</span></div></div>
<div class=" item_text " style="margin-left:2em">
<p style="margin-top:0em; margin-bottom:0em">
The <a class="local" href="../doc/zum.html">Zoem User Manual</a>.
</p>
</div>
<div class=" item_compact"><div class=" item_rightalign " style="right:-1em"><span class="itembullet">&bull;</span></div></div>
<div class=" item_text " style="margin-left:2em">
<p style="margin-top:0em; margin-bottom:0em">
The <a class="local sibling" href="pud-man.html">pud-man</a> manual page.
</p>
</div>
</div>

<a name="toc"></a>
<h2>TOC</h2>
<hr>
<div class=" itemize " style="margin-top:0em; font-size:100%">
<div class=" item_compact"><div class=" item_leftalign nowrap " ><a name="toc-s_basics"></a><a class="quiet" href="#s_basics"><b>1</b></a></div></div>
<div class=" item_text " style="margin-left:2em">
<a class="quiet" href="#s_basics"><b>How do I create and link to questions and sections?</b></a>
</div>
<div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-1em"><a name="toc-qsection"></a> <a class="intern" href="#qsection"><b>1.1</b></a></div></div>
<div class=" item_text " style="margin-left:2em">
<a class="intern" href="#qsection"><b>How do I start a section?</b></a>
</div>
<div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-1em"><a name="toc-q_question"></a> <a class="intern" href="#q_question"><b>1.2</b></a></div></div>
<div class=" item_text " style="margin-left:2em">
<a class="intern" href="#q_question"><b>How do I make a faq entry?</b></a>
</div>
<div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-1em"><a name="toc-q_qlink"></a> <a class="intern" href="#q_qlink"><b>1.3</b></a></div></div>
<div class=" item_text " style="margin-left:2em">
<a class="intern" href="#q_qlink"><b>How do I link to a question?</b></a>
</div>
<div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-1em"><a name="toc-q_slink"></a> <a class="intern" href="#q_slink"><b>1.4</b></a></div></div>
<div class=" item_text " style="margin-left:2em">
<a class="intern" href="#q_slink"><b>How do I link to a section?</b></a>
</div>
<div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-1em"><a name="toc-q_typing"></a> <a class="intern" href="#q_typing"><b>1.5</b></a></div></div>
<div class=" item_text " style="margin-left:2em">
<a class="intern" href="#q_typing"><b>Is that not a whole lot of typing just for linking?</b></a>
</div>
</div>
<hr>
<div class=" itemize " style="margin-top:0em; font-size:100%">
<div class=" item_compact"><div class=" item_leftalign nowrap " ><a name="toc-s_stupid"></a><a class="quiet" href="#s_stupid"><b>2</b></a></div></div>
<div class=" item_text " style="margin-left:2em">
<a class="quiet" href="#s_stupid"><b>Miscellaneous</b></a>
</div>
<div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-1em"><a name="toc-q_really"></a> <a class="intern" href="#q_really"><b>2.1</b></a></div></div>
<div class=" item_text " style="margin-left:2em">
<a class="intern" href="#q_really"><b>Is it really possible to have more than one section?</b></a>
</div>
<div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-1em"><a name="toc-q_toc"></a> <a class="intern" href="#q_toc"><b>2.2</b></a></div></div>
<div class=" item_text " style="margin-left:2em">
<a class="intern" href="#q_toc"><b>Is there an easy way to get back to the TOC?</b></a>
</div>
<div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-1em"><a name="toc-q_real"></a> <a class="intern" href="#q_real"><b>2.3</b></a></div></div>
<div class=" item_text " style="margin-left:2em">
<a class="intern" href="#q_real"><b>Show me a real FAQ, not this nonsense.</b></a>
</div>
<div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-1em"><a name="toc-q_change"></a> <a class="intern" href="#q_change"><b>2.4</b></a></div></div>
<div class=" item_text " style="margin-left:2em">
<a class="intern" href="#q_change"><b>I want to change the appearance of my FAQ.</b></a>
</div>
<div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-1em"><a name="toc-q_self"></a> <a class="intern" href="#q_self"><b>2.5</b></a></div></div>
<div class=" item_text " style="margin-left:2em">
<a class="intern" href="#q_self"><b>Show me the source to this FAQ.</b></a>
</div>
</div>
<br><br>

<a name="faq"></a>
<h2>FAQ</h2>

<div align=center>
<h3><a name="s_basics"></a><a class="quiet" href="#toc-s_basics">1</a><br>How do I create and link to questions and sections?
</h3>
</div>

<div class=" itemize " style="margin-top:1em; font-size:100%">
<div class=" item_compact"><div class=" item_leftalign nowrap " ><a name="qsection"></a> <a class="quiet" href="#toc-s_basics">1.1</a></div></div>
<div class=" item_text " style="margin-left:2em">
<b>How do I start a section?</b>
<p style="margin-top:0em; margin-bottom:0em">
You would for example type
</p>
<div class="verbatim">\begin{faqsec}{
   {ref}{kind}
   {cap}{How do I link to questions and sections?}
}</div>
</div>
<div style="margin-top:0em">&nbsp;</div><div class=" item_compact"><div class=" item_leftalign nowrap " ><a name="q_question"></a> <a class="quiet" href="#toc-s_basics">1.2</a></div></div>
<div class=" item_text " style="margin-left:2em">
<b>How do I make a faq entry?</b>
<p style="margin-top:0em; margin-bottom:0em">
You create an entry as follows:
</p>
<div class="verbatim">\faq{q_question}{How do I make a faq entry?}
   You create an entry as follows:
   ...
</div>
</div>
<div style="margin-top:0em">&nbsp;</div><div class=" item_compact"><div class=" item_leftalign nowrap " ><a name="q_qlink"></a> <a class="quiet" href="#toc-s_basics">1.3</a></div></div>
<div class=" item_text " style="margin-left:2em">
<b>How do I link to a question?</b>
<div class="verbatim">\car{Like this: linking to
\iref{q_qlink}{Question\~\refnumber{q_qlink}},
or a silly link to the \iref{q_qlink}{current question}.
Linking to \iref{s_basics}{Question\~\refnumber{q_slink}},
or a link to the \iref{q_slink}{next question}.}

\par{
Of course, you have to use wordings such that the
text still makes sense in the absence of links
(assuming you are intested in the troff version of
the FAQ you are writing), so normally you just refer to
\iref{q_slink}{Question\~\refnumber{q_slink}} and be done
with it.}</div>
<p style="margin-top:0em; margin-bottom:0em">Like this: linking to
<a class="intern" href="#q_qlink">Question&nbsp;1.3</a>,
or a silly link to the <a class="intern" href="#q_qlink">current question</a>.
Linking to <a class="intern" href="#s_basics">Question&nbsp;1.4</a>,
or a link to the <a class="intern" href="#q_slink">next question</a>.</p>
<p style="margin-bottom:0" class="asd_par">
Of course, you have to use wordings such that the
text still makes sense in the absence of links
(assuming you are intested in the troff version of
the FAQ you are writing), so normally you just refer to
<a class="intern" href="#q_slink">Question&nbsp;1.4</a> and be done
with it.</p>
</div>
<div style="margin-top:0em">&nbsp;</div><div class=" item_compact"><div class=" item_leftalign nowrap " ><a name="q_slink"></a> <a class="quiet" href="#toc-s_basics">1.4</a></div></div>
<div class=" item_text " style="margin-left:2em">
<b>How do I link to a section?</b>
<div class="verbatim">\car{Like this: linking to
\iref{q_qlink}{Section\~\refnumber{s_basics}} and
linking to \iref{q_stupid}{Section\~\refnumber{s_stupid}}.}</div>
<p style="margin-top:0em; margin-bottom:0em">Like this: linking to
<a class="intern" href="#q_qlink">Section&nbsp;1</a> and
linking to <a class="intern" href="#q_stupid">Section&nbsp;2</a>.</p>
</div>
<div style="margin-top:0em">&nbsp;</div><div class=" item_compact"><div class=" item_leftalign nowrap " ><a name="q_typing"></a> <a class="quiet" href="#toc-s_basics">1.5</a></div></div>
<div class=" item_text " style="margin-left:2em">
<b>Is that not a whole lot of typing just for linking?</b>
<p style="margin-top:0em; margin-bottom:0em">
It sure is. Note the repeating elements though. Feel free to create your own
shortcuts by using Zoem's macro facilities.
</p>
</div>
</div>

<div align=center>
<h3><a name="s_stupid"></a><a class="quiet" href="#toc-s_stupid">2</a><br>Miscellaneous
</h3>
</div>

<div class=" itemize " style="margin-top:1em; font-size:100%">
<div class=" item_compact"><div class=" item_leftalign nowrap " ><a name="q_really"></a> <a class="quiet" href="#toc-s_stupid">2.1</a></div></div>
<div class=" item_text " style="margin-left:2em">
<b>Is it really possible to have more than one section?</b>
<p style="margin-top:0em; margin-bottom:0em">
QED
</p>
</div>
<div style="margin-top:0em">&nbsp;</div><div class=" item_compact"><div class=" item_leftalign nowrap " ><a name="q_toc"></a> <a class="quiet" href="#toc-s_stupid">2.2</a></div></div>
<div class=" item_text " style="margin-left:2em">
<b>Is there an easy way to get back to the TOC?</b>
<p style="margin-top:0em; margin-bottom:0em">
In the HTML version of the faq, one can click on the number
to the left of the question; this will take you to the top
of the TOC part pertaining to the section that question belongs to.</p>
</div>
<div style="margin-top:0em">&nbsp;</div><div class=" item_compact"><div class=" item_leftalign nowrap " ><a name="q_real"></a> <a class="quiet" href="#toc-s_stupid">2.3</a></div></div>
<div class=" item_text " style="margin-left:2em">
<b>Show me a real FAQ, not this nonsense.</b>
<p style="margin-top:0em; margin-bottom:0em">
The reason I began writing zoem and PUD was that I wanted decent (both
HTML and troff) and easy to write documentation for my implementation
of the MCL cluster algorithm.</p>
<div class=" itemize " style="margin-top:1em; font-size:100%">
<div class=" item_compact"><div class=" item_rightalign " style="right:-1em"><span class="itembullet">&bull;</span></div></div>
<div class=" item_text " style="margin-left:2em">
<a class="extern" href="http://micans.org/mcl/src/mcl-latest/doc/mclfaq.azm">http://micans.org/mcl/src/mcl-latest/doc/mclfaq.azm</a>
</div>
<div class=" item_compact"><div class=" item_rightalign " style="right:-1em"><span class="itembullet">&bull;</span></div></div>
<div class=" item_text " style="margin-left:2em">
<a class="extern" href="http://micans.org/mcl/src/mcl-latest/doc/mclfaq.html">http://micans.org/mcl/src/mcl-latest/doc/mclfaq.html</a>
</div>
<div class=" item_compact"><div class=" item_rightalign " style="right:-1em"><span class="itembullet">&bull;</span></div></div>
<div class=" item_text " style="margin-left:2em">
<a class="extern" href="http://micans.org/mcl/src/mcl-latest/doc/mclfaq.ps">http://micans.org/mcl/src/mcl-latest/doc/mclfaq.ps</a>
</div>
</div>
</div>
<div style="margin-top:0em">&nbsp;</div><div class=" item_compact"><div class=" item_leftalign nowrap " ><a name="q_change"></a> <a class="quiet" href="#toc-s_stupid">2.4</a></div></div>
<div class=" item_text " style="margin-left:2em">
<b>I want to change the appearance of my FAQ.</b>
Well, you need to make a copy of the faq macros and
possibly the man macros, and hack those changes in.
Zoem itself is very flexible, but the PUD faq macros
are not, in this respect. They can be made so, if you wish.
If you just want to change or add some style sheet rules for
the HTML version, it will be quite easy.
The same holds for changing font styles and possibly
even spacing rules.
</div>
<div style="margin-top:0em">&nbsp;</div><div class=" item_compact"><div class=" item_leftalign nowrap " ><a name="q_self"></a> <a class="quiet" href="#toc-s_stupid">2.5</a></div></div>
<div class=" item_text " style="margin-left:2em">
<b>Show me the source to this FAQ.</b>
<a class="local" href="pud-faq.azm">Behold pud-faq.azm.</a>
Take note though that I played a few silly tricks in this FAQ,
so the source looks more unreadable than your average FAQ.
The FAQ pointed to in <a class="intern" href="#q_real">Answer&nbsp;2.3</a>
gives a more realistic impression.
</div>
</div>

<a name="author"></a>
<h2>AUTHOR</h2>
<p style="margin-bottom:0" class="asd_par">
Stijn van Dongen.
</p>

<a name="seealso"></a>
<h2>SEE ALSO</h2>
<p style="margin-bottom:0" class="asd_par">
The <a class="local sibling" href="pud-man.html">pud-man</a> manual page, documenting
the PUD manual language. The FAQ language imports the manual
definitions and you use these e.g. for sectioning commands
as described above.</p>
<p style="margin-bottom:0" class="asd_par">
The <a class="local sibling" href="pud.html">pud</a> manual page gives an overview of PUD.</p>
</body>
</html>

Perl :: Catalyst :: PostgreSQL :: RPM Valid HTML 4.01 Transitional