From: "Xavier Neys" <neysx@lark.gentoo.org>
To: gentoo-doc-cvs@lists.gentoo.org
Subject: [gentoo-doc-cvs] cvs commit: xml-guide.xml
Date: Sun, 9 Oct 2005 11:00:20 +0000 [thread overview]
Message-ID: <200510091051.j99ApNne016288@robin.gentoo.org> (raw)
neysx 05/10/09 11:00:20
Modified: xml/htdocs/doc/en xml-guide.xml
Log:
Documented disclaimers and some extra fixes
Revision Changes Path
1.51 +85 -29 xml/htdocs/doc/en/xml-guide.xml
file : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/xml-guide.xml?rev=1.51&content-type=text/x-cvsweb-markup&cvsroot=gentoo
plain: http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/xml-guide.xml?rev=1.51&content-type=text/plain&cvsroot=gentoo
diff : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/xml-guide.xml.diff?r1=1.50&r2=1.51&cvsroot=gentoo
Index: xml-guide.xml
===================================================================
RCS file: /var/cvsroot/gentoo/xml/htdocs/doc/en/xml-guide.xml,v
retrieving revision 1.50
retrieving revision 1.51
diff -u -r1.50 -r1.51
--- xml-guide.xml 9 Oct 2005 06:07:09 -0000 1.50
+++ xml-guide.xml 9 Oct 2005 11:00:20 -0000 1.51
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="UTF-8"?>
-<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/xml-guide.xml,v 1.50 2005/10/09 06:07:09 vapier Exp $ -->
+<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/xml-guide.xml,v 1.51 2005/10/09 11:00:20 neysx Exp $ -->
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
<guide link="/doc/en/xml-guide.xml">
@@ -113,16 +113,18 @@
On the first lines, we see the requisite tag that identifies this as an XML
document and specifies its DTD. The <c><!-- $Header$ --></c> line
will be automatically modified by the CVS server and helps to track revisions.
-Next, there's a <c><guide></c> tag -- the entire guide document is
-enclosed within a <c><guide> </guide></c> pair. The <c>link</c>
+Next, there's a <c><guide></c> tag -- the entire guide document is
+enclosed within a <c><guide> </guide></c> pair. The <c>link</c>
attribute is compulsory and should preferably contain the absolute path to the
document relatively to the document root even though the file name alone will
work. It is mainly used to generate a link to a printer-friendly version of
-your document. If you use a wrong value, the link to the printable version
-will either not work or point to a wrong document. The <c>lang</c> attribute
-can be used to specify the language code of your document. It is used to format
-the date and insert strings like "<e>Note</e>", "<e>Content</e>", etc. in the
-specified language. The default is English.
+your document. If you use a wrong value, the link to the printable version will
+either not work or point to a wrong document. Translated documents <e>must</e>
+specify the full path because it is also used to check whether a more recent
+original document exists. The <c>lang</c> attribute should be used to specify
+the language code of your document. It is used to format the date and insert
+strings like "<e>Note</e>", "<e>Content</e>", etc. in the specified language.
+The default is English.
</p>
<p>
@@ -305,11 +307,11 @@
stacked -- in other words, don't put a <c><note></c> element inside a
<c><p></c> element. As you might guess, the <c><pre></c> element
preserves its whitespace exactly, making it well-suited for code excerpts.
-You can also name the <c><pre></c> tag:
+You must name the <c><pre></c> tag with a caption attribute:
</p>
<pre caption="Named <pre>">
-<pre caption = "Output of uptime">
+<pre caption="Output of uptime">
# <i>uptime</i>
16:50:47 up 164 days, 2:06, 5 users, load average: 0.23, 0.20, 0.25
</pre>
@@ -318,11 +320,11 @@
</body>
</section>
<section>
-<title><path>, <c>, <i> and <e></title>
+<title><path>, <c>, <i>, <b> and <e></title>
<body>
<p>
-The <c><path></c>, <c><c></c> and <c><e></c> elements can
+The <c><path></c>, <c><c></c>, <c><b></c> and <c><e></c> elements can
be used inside any child <c><body></c> tag, except for
<c><pre></c>. The <c><i></c> element can only be used inside
<c><pre></c>.
@@ -356,6 +358,11 @@
</p>
<p>
+As you might have guessed, <c><b></c> is used to <b>boldface</b> some
+text.
+</p>
+
+<p>
<c><e></c> is used to apply emphasis to a word or phrase; for example:
I <e>really</e> should use semicolons more often. As you can see, this text is
offset from the regular paragraph type for emphasis. This helps to give your
@@ -369,9 +376,11 @@
<body>
<p>
-We've taken a look at the <c><mail></c> tag earlier; it's used to link
-some text with a particular email address, and takes the form <c><mail
-link="foo@bar.com">Mr. Foo Bar</mail></c>.
+We've taken a look at the <c><mail></c> tag earlier; it's used to link
+some text with a particular email address, and takes the form <c><mail
+link="foo@bar.com">Mr. Foo Bar</mail></c>. If you want to display the
+email address, you can use <c><mail>foo@bar.com</mail></c>, this
+would be displayed as <mail>foo@bar.com</mail>.
</p>
<p>
@@ -414,15 +423,14 @@
<body>
<p>
-Guide supports a simplified table syntax similar to that of HTML. To start
-a table, use a <c><table></c> tag. Start a row with a <c><tr></c>
+Guide supports a simplified table syntax similar to that of HTML. To start a
+table, use a <c><table></c> tag. Start a row with a <c><tr></c>
tag. However, for inserting actual table data, we <e>don't</e> support the
HTML <td> tag; instead, use the <c><th></c> if you are inserting a
header, and <c><ti></c> if you are inserting a normal informational
-block. You can use a <c><th></c> anywhere you can use a <c><ti></c>
--- there's no requirement that <c><th></c> elements appear only in the
-first row. Currently, these tags don't support any attributes, but some might
-be added (such as a <c>caption=</c> attribute for <c><table></c>) later.
+block. You can use a <c><th></c> anywhere you can use a <c><ti></c>
+-- there's no requirement that <c><th></c> elements appear only in the
+first row.
</p>
<p>
@@ -470,6 +478,51 @@
</body>
</section>
+<section>
+<title>Disclaimers and obsolete documents</title>
+<body>
+
+<p>
+A disclaimer attribute can be applied to guides and handbooks to display a predefined disclaimer at the top of the document. The available disclaimers are:
+</p>
+
+<ul>
+ <li>
+ <b>articles</b> is used for <uri link="/doc/en/articles/">republished
+ articles</uri>
+ </li>
+ <li>
+ <b>draft</b> is used to indicate a document is still being worked on and
+ should not be considered official
+ </li>
+ <li>
+ <b>oldbook</b> is used on old handbooks to indicate they are not maintained
+ anymore
+ </li>
+ <li><b>obsolete</b> is used to mark a document as obsolete.</li>
+</ul>
+
+<p>
+When marking a document as obsolete, you might want to add a link to a new
+version. The <c>redirect</c> attribute does just that. The user might be
+automatically redirected to the new page but you should not rely on that
+behaviour.
+</p>
+
+<pre caption="Disclaimer sample">
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
+<!-- $Header$ -->
+
+<guide link="/doc/en/gentoo-x86-install.xml" disclaimer="obsolete" redirect="/doc/en/handbook/handbook-x86.xml">
+<title>Gentoo x86 Installation Guide</title>
+
+<author title="Author">
+...
+</pre>
+
+</body>
+</section>
</chapter>
<chapter>
@@ -517,17 +570,20 @@
<p>
<b>Word-wrapping</b> must be applied at 80 characters except inside
-<c><pre></c>. Only when there is no other choice can be deviated from
-this rule (for instance when a URL exceeds the maximum amount of characters).
-The editor must then wrap whenever the first whitespace occurs.
+<c><pre></c>. You may only deviate from this rule when there is no other
+choice (for instance when a URL exceeds the maximum amount of characters). The
+editor must then wrap whenever the first whitespace occurs. You should try to
+keep the <e>rendered</e> content of <c><pre></c> elements within 80
+columns to help console users.
</p>
<p>
-<b>Indentation</b> may not be used, except with the XML-constructs of which
-the parent XML-tags are <c><tr></c> (from <c><table></c>),
-<c><ul></c>, <c><ol></c> and <c><author></c>. If indentation
-is used, it <e>must</e> be two spaces for each indentation. That means <e>no</e>
-tabs and <e>not</e> more spaces.
+<b>Indentation</b> may not be used, except with the XML-constructs of which the
+parent XML-tags are <c><tr></c> (from <c><table></c>),
+<c><ul></c>, <c><ol></c> and <c><author></c>. If indentation
+is used, it <e>must</e> be two spaces for each indentation. That means <e>no
+tabs</e> and <e>not</e> more spaces. Besides, tabs are not allowed in GuideXML
+documents.
</p>
<p>
--
gentoo-doc-cvs@gentoo.org mailing list
next reply other threads:[~2005-10-09 11:00 UTC|newest]
Thread overview: 20+ messages / expand[flat|nested] mbox.gz Atom feed top
2005-10-09 11:00 Xavier Neys [this message]
-- strict thread matches above, loose matches on Subject: below --
2008-03-09 13:13 [gentoo-doc-cvs] cvs commit: xml-guide.xml Xavier Neys
2007-10-04 19:37 Xavier Neys
2006-05-11 17:07 Lukasz Damentko
2006-05-07 14:41 Lukasz Damentko
2006-05-07 14:36 Lukasz Damentko
2006-04-26 10:26 Xavier Neys
2006-04-10 9:15 Xavier Neys
2006-04-10 9:11 Xavier Neys
2006-02-20 12:17 Xavier Neys
2006-01-09 14:44 Xavier Neys
2005-12-31 17:17 Xavier Neys
2005-12-19 17:57 Xavier Neys
2005-10-13 20:47 Alin Dobre
2005-10-13 20:33 Xavier Neys
2005-10-13 15:57 Xavier Neys
2005-10-09 6:07 vapier
2005-08-23 9:18 Xavier Neys
2005-08-11 11:01 swift
2005-07-26 11:51 Xavier Neys
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=200510091051.j99ApNne016288@robin.gentoo.org \
--to=neysx@lark.gentoo.org \
--cc=docs-team@lists.gentoo.org \
--cc=gentoo-doc-cvs@lists.gentoo.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox