* [gentoo-commits] proj/devmanual:master commit in: appendices/devbook-guide/
@ 2020-01-15 21:29 Ulrich Müller
0 siblings, 0 replies; 30+ messages in thread
From: Ulrich Müller @ 2020-01-15 21:29 UTC (permalink / raw
To: gentoo-commits
commit: eda9eff6a5393887b56679df3ff9c4107e1e4674
Author: Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Sat Jan 11 19:44:54 2020 +0000
Commit: Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Wed Jan 15 21:28:46 2020 +0000
URL: https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=eda9eff6
devbook-guide: Update section on intra-document references.
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>
appendices/devbook-guide/text.xml | 25 +++++++++++++++++--------
1 file changed, 17 insertions(+), 8 deletions(-)
diff --git a/appendices/devbook-guide/text.xml b/appendices/devbook-guide/text.xml
index 0f0a3ad..3b583f2 100644
--- a/appendices/devbook-guide/text.xml
+++ b/appendices/devbook-guide/text.xml
@@ -469,14 +469,23 @@ admonitions. A definition list comprises:
<p>
GuideXML makes it really easy to reference other parts of the document using
-hyperlinks. You can create a link pointing to <uri link="#doc_chap1">Chapter
-One</uri> by typing <c><uri link="#doc_chap1">Chapter
-One</uri></c>. To point to <uri link="#doc_chap1_sect2">section two of
-Chapter One</uri>, type <c><uri link="#doc_chap1_sect2">section two of
-Chapter One</uri></c>. To refer to figure 3 in chapter 1, type
-<c><uri link="#doc_chap1_fig3">figure 1.3</uri></c>. Or, to refer
-to <uri link="#doc_chap2_pre2">code listing 2 in chapter 2</uri>, type
-<c><uri link="#doc_chap2_pre2">code listing 2.2</uri></c>.
+hyperlinks. You can create a link pointing to another chapter, like
+<uri link="::ebuild-writing/file-format/">Ebuild File Format</uri>, by typing
+<c><uri link="::ebuild-writing/file-format/">Ebuild File
+Format</uri></c>, i.e., two colons followed by the relative path from
+the root node. To refer to a section in another chapter, like
+<uri link="::quickstart/#First Ebuild">First Ebuild</uri>, type
+<c><uri link="::quickstart/#First Ebuild">First Ebuild</uri></c>.
+</p>
+
+<p>
+If the link target's chapter (or section etc.) title is to be used as the link
+text, an empty <c><uri></c> element can be used. As a matter of fact,
+I could have written the two examples above in more compact form:
+<c><uri link="::ebuild-writing/file-format/"/></c> and
+<c><uri link="::quickstart/#First Ebuild"/></c> render as
+<uri link="::ebuild-writing/file-format/"/> and
+<uri link="::quickstart#First Ebuild"/>, respectively.
</p>
</body>
^ permalink raw reply related [flat|nested] 30+ messages in thread
* [gentoo-commits] proj/devmanual:master commit in: appendices/devbook-guide/
@ 2020-01-15 21:29 Ulrich Müller
0 siblings, 0 replies; 30+ messages in thread
From: Ulrich Müller @ 2020-01-15 21:29 UTC (permalink / raw
To: gentoo-commits
commit: 3a84fac87dd431fbfbdddf51dcf34e6bcc71b6c6
Author: Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Sat Jan 11 20:05:40 2020 +0000
Commit: Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Wed Jan 15 21:28:46 2020 +0000
URL: https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=3a84fac8
devbook-guide: Section on including sub-documents.
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>
appendices/devbook-guide/text.xml | 27 +++++++++++++++++++++++++++
1 file changed, 27 insertions(+)
diff --git a/appendices/devbook-guide/text.xml b/appendices/devbook-guide/text.xml
index 3b583f2..1e73104 100644
--- a/appendices/devbook-guide/text.xml
+++ b/appendices/devbook-guide/text.xml
@@ -122,6 +122,33 @@ any number of section elements of the next lower level. Skipping of levels is
not allowed, e.g., a subsection cannot be directly below a chapter.
</note>
+</body>
+</subsection>
+<subsection>
+<title>Including sub-documents</title>
+<body>
+
+<p>
+The manual is organized as a tree. Each directory contains one document, which
+can include multiple sub-documents using the <c><include href="foo/"/></c>
+tag. Note that the trailing slash in the <c>href</c> value is mandatory.
+</p>
+
+<p>
+A table of contents can be generated with <c><contentsTree></c>.
+Typically, this tag would be the only element in its own section body, as in
+the following example:
+</p>
+
+<codesample lang="sgml">
+<section>
+<title>Contents</title>
+<body>
+<contentsTree/>
+</body>
+</section>
+</codesample>
+
</body>
</subsection>
<subsection>
^ permalink raw reply related [flat|nested] 30+ messages in thread
* [gentoo-commits] proj/devmanual:master commit in: appendices/devbook-guide/
@ 2020-01-15 21:29 Ulrich Müller
0 siblings, 0 replies; 30+ messages in thread
From: Ulrich Müller @ 2020-01-15 21:29 UTC (permalink / raw
To: gentoo-commits
commit: a8c06515b2da4df8a858e21c72ce446dd6abd998
Author: Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Sat Jan 11 08:33:46 2020 +0000
Commit: Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Wed Jan 15 21:28:44 2020 +0000
URL: https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=a8c06515
devbook-guide: Update basic document structure for DevBook XML.
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>
appendices/devbook-guide/text.xml | 150 +++++++++++++-------------------------
1 file changed, 51 insertions(+), 99 deletions(-)
diff --git a/appendices/devbook-guide/text.xml b/appendices/devbook-guide/text.xml
index 453820e..025a8b1 100644
--- a/appendices/devbook-guide/text.xml
+++ b/appendices/devbook-guide/text.xml
@@ -39,135 +39,87 @@ tags used in a GuideXML document:
<codesample lang="sgml"><!-- The initial part of a guide XML document -->
<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
-<!-- $Header$ -->
-
-<guide lang="en">
-<title>Gentoo Documentation Guide</title>
-
-<author title="Author">
- <mail link="yourname@gentoo.org">Your Name</mail>
-</author>
-
-<abstract>
-This guide shows you how to compose web documentation using
-our new lightweight Gentoo GuideXML syntax. This syntax is the official
-format for Gentoo web documentation, and this document itself was created
-using GuideXML.
-</abstract>
-
-<!-- The content of this document is licensed under the CC-BY-SA license -->
-<!-- See https://creativecommons.org/licenses/by-sa/3.0 -->
-<license version="3.0"/>
-
-<version>1</version>
-<date>2011-11-29</date>
+<guide self="appendices/devbook-guide/">
+<chapter>
+<title>Gentoo GuideXML Guide</title>
</codesample>
<p>
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 <d/> the entire guide document is
-enclosed within a <c><guide> </guide></c> pair.
-</p>
-
-<p>
-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>
-Next, there's a <c><title></c> tag, used to set the title for the entire
-guide document.
+document. Next, there's a <c><guide></c> tag <d/> the entire document is
+enclosed within a <c><guide> </guide></c> pair. Its <c>self</c>
+attribute must point to the relative path of the document from the root node;
+in the example above the path is <c>appendices/devbook-guide/</c>. An exception
+is the root node itself, which has <c><guide root="true"></c> instead.
</p>
<p>
-Then, we come to the <c><author></c> tags, which contain information
-about the various authors of the document. Each <c><author></c> tag
-allows for an optional <c>title</c> element, used to specify the author's
-relationship to the document (author, co-author, editor, etc.). In this
-particular example, the authors' names are enclosed in another tag <d/> a
-<c><mail></c> tag, used to specify an email address for this particular
-person. The <c><mail></c> tag is optional and can be omitted, and at
-least one <c><author></c> element is required per guide document.
+Next, there is a <c><chapter></c> tag. Every document must have exactly
+one chapter. Its <c><title></c> is used to set the title for the entire
+document.
</p>
-<p>
-Next, we come to the <c><abstract></c>, <c><version></c> and
-<c><date></c> tags, used to specify a summary of the document, the
-current version number, and the current version date (in YYYY-MM-DD format)
-respectively. Dates that are invalid or not in the YYYY-MM-DD format will
-appear verbatim in the rendered document.
-</p>
+<important>
+The <c><title></c> element cannot contain any newlines. Make sure it is
+in one line, including its opening and closing tags.
+</important>
<p>
-This sums up the tags that should appear at the beginning of a guide document.
-Besides the <c><title></c> and <c><mail></c> tags, these tags
-shouldn't appear anywhere else except immediately inside the
-<c><guide></c> tag, and for consistency it's recommended (but not
-required) that these tags appear before the content of the document.
+All tags must be closed of course, so the document ends with:
</p>
-<p>
-Finally we have the <c><license version="3.0"/></c> tag, used to publish
-the document under the <uri link="https://creativecommons.org/licenses/by-sa/3.0/">Creative
-Commons - Attribution / Share Alike</uri> license as required by the <uri
-link="/proj/en/gdp/doc/doc-policy.xml">Documentation Policy</uri>. Historically,
-the tag <c><license /></c> was used, which denoted the 2.5 version of the
-license. This is still accepted/allowed.
-</p>
+<codesample lang="sgml">
+</chapter>
+</guide>
+</codesample>
</body>
</subsection>
<subsection>
-<title>Chapters and sections</title>
+<title>Sections and subsections</title>
<body>
<p>
Once the initial tags have been specified, you're ready to start adding the
-structural elements of the document. Guide documents are divided into
-chapters, and each chapter can hold one or more sections. Every chapter and
-section has a title. Here's an example chapter with a single section,
-consisting of a paragraph. If you append this XML to the XML in the <uri
-link="#doc_chap2_pre1">previous excerpt</uri> and append a
-<c></guide></c> to the end of the file, you'll have a valid (if minimal)
-guide document:
+structural elements of the document. Chapters are divided into sections;
+each section can hold zero or more subsections, which can contain zero or more
+subsubsections. Section, subsection and subsubsection elements must have a
+title. Here's an example section with a single subsection, consisting of a
+paragraph:
</p>
<codesample lang="sgml"><!-- Minimal guide example -->
-<chapter>
-<title>This is my chapter</title>
<section>
-<title>This is section one of my chapter</title>
+<title>This is my section</title>
+<subsection>
+<title>This is subsection one of my section</title>
<body>
<p>
-This is the actual text content of my section.
+This is the actual text content of my subsection.
</p>
</body>
+</subsection>
</section>
-</chapter>
</codesample>
<p>
-Above, I set the chapter title by adding a child <c><title></c>
-element to the <c><chapter></c> element. Then, I created a section by
-adding a <c><section></c> element. If you look inside the
-<c><section></c> element, you'll see that it has two child elements <d/> a
-<c><title></c> and a <c><body></c>. While the <c><title></c>
-is nothing new, the <c><body></c> is <d/> it contains the actual text
-content of this particular section. We'll look at the tags that are allowed
-inside a <c><body></c> element in a bit.
+Above, I set the section title by adding a child <c><title></c> element
+to the <c><section></c> element. Then, I created a subsection by adding
+a <c><subsection></c> element. If you look inside the
+<c><subsection></c> element, you'll see that it has two child elements
+<d/> a <c><title></c> and a <c><body></c>. While the
+<c><title></c> is nothing new, the <c><body></c> is <d/>
+it contains the actual text content of this particular subsection. We'll look
+at the tags that are allowed inside a <c><body></c> element in a bit.
</p>
<note>
-A <c><guide></c> element must contain at least one <c><chapter></c>
-elements, a <c><chapter></c> must contain at least one
-<c><section></c> elements and a <c><section></c> element must
-contain at least one <c><body></c> element.
+The <c><chapter></c>, <c><section></c>, <c><subsection></c>
+and <c><subsubsection></c>) elements contain a <c><body></c> and/or
+any number of section elements of the next lower level. Skipping of levels is
+not allowed, e.g., a subsection cannot be directly below a chapter.
</note>
</body>
@@ -502,10 +454,10 @@ GuideXML-tag (both opening as closing), except for:
<p>
<b>Blank lines</b> must be placed immediately after <e>every</e>
<c><body></c> (opening tag only) and before <e>every</e>
-<c><chapter></c>, <c><p></c>, <c><table></c>,
-<c><author></c> (set), <c><pre></c>, <c><ul></c>,
-<c><ol></c>, <c><warning></c>, <c><note></c> and
-<c><important></c> (opening tags only).
+<c><section></c>, <c><p></c>, <c><pre></c>,
+<c><codesample></c>, <c><figure;></c>, <c><table></c>,
+<c><ul></c>, <c><ol></c>, <c><dl></c>, <c><note></c>
+<c><important></c> and <c><warning></c> (opening tags only).
</p>
<p>
@@ -520,10 +472,10 @@ columns to help console users.
<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>, <c><dl></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.
+<c><ul></c>, <c><ol></c> and <c><dl></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>
^ permalink raw reply related [flat|nested] 30+ messages in thread
* [gentoo-commits] proj/devmanual:master commit in: appendices/devbook-guide/
@ 2020-01-15 21:29 Ulrich Müller
0 siblings, 0 replies; 30+ messages in thread
From: Ulrich Müller @ 2020-01-15 21:29 UTC (permalink / raw
To: gentoo-commits
commit: 46fe68d000cd1dfd48ddbb829ce8a3a1ad24e19f
Author: Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Sat Jan 11 09:03:49 2020 +0000
Commit: Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Wed Jan 15 21:28:44 2020 +0000
URL: https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=46fe68d0
devbook-guide: Make codesamples agree with their rendering.
Mention <figure> and <codesample> as subelements of <body>.
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>
appendices/devbook-guide/text.xml | 35 ++++++++++++++++++++---------------
1 file changed, 20 insertions(+), 15 deletions(-)
diff --git a/appendices/devbook-guide/text.xml b/appendices/devbook-guide/text.xml
index 025a8b1..5ae077b 100644
--- a/appendices/devbook-guide/text.xml
+++ b/appendices/devbook-guide/text.xml
@@ -135,18 +135,20 @@ an example <c><body></c> element:
<codesample lang="sgml"><!-- Example of a body element -->
<p>
-This is a paragraph. <path>/etc/passwd</path> is a file.
+This is a paragraph. <c>/etc/passwd</c> is a file.
<uri>https://forums.gentoo.org</uri> is my favorite website.
-Type <c>ls</c> if you feel like it. I <e>really</e> want to go to sleep now.
+Type <c>ls</c> if you feel like it. I <e>really</e> want to go to sleep now.
</p>
<pre>
This is text output or code.
-# <i>this is user input</i>
+# this is user input
+</pre>
+<codesample lang="sgml">
Make HTML/XML easier to read by using selective emphasis:
-<foo><i>bar</i></foo>
-</pre>
+&lt;foo&gt;bar&lt;/foo&gt;
+</codesample>
<note>
This is a note.
@@ -166,15 +168,17 @@ Now, here's how the <c><body></c> element above is rendered:
</p>
<p>
-This is a paragraph. <c>/etc/passwd</c> is a file.
+This is a paragraph. <c>/etc/passwd</c> is a file.
<uri>https://forums.gentoo.org</uri> is my favorite web site.
-Type <c>ls</c> if you feel like it. I <e>really</e> want to go to sleep now.
+Type <c>ls</c> if you feel like it. I <e>really</e> want to go to sleep now.
</p>
-<codesample lang="sgml"><!-- Code Sample -->
+<pre>
This is text output or code.
# this is user input
+</pre>
+<codesample lang="sgml">
Make HTML/XML easier to read by using selective emphasis:
<foo>bar</foo>
</codesample>
@@ -199,21 +203,22 @@ This is important.
<p>
We introduced a lot of new tags in the previous section <d/> here's what you
-need to know. The <c><p></c> (paragraph), <c><pre></c> (code block),
-<c><note></c>, <c><warning></c> (warning) and
-<c><important></c> (important) tags all can contain one or more lines of
-text. Besides the <c><table></c>, <c><ul></c>, <c><ol></c>
+need to know. The <c><p></c> (paragraph), <c><pre></c>
+(preformatted block), <c><codesample></c> (code block),
+<c><note></c>, <c><warning></c> and <c><important></c> tags
+all can contain one or more lines of text. Besides the <c><figure></c>,
+<c><table></c>, <c><ul></c>, <c><ol></c>
and <c><dl></c> elements (which we'll cover in just a bit), these are the
only tags that should appear immediately inside a <c><body></c> element.
Another thing <d/> these tags <e>should not</e> be stacked <d/> 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 might guess, the <c><pre></c> and <c><codesample></c> elements
+preserve their whitespace exactly, making them well-suited for code excerpts:
</p>
<codesample lang="sgml"><!-- Named <pre> -->
<pre>
-# <i>uptime</i>
+# uptime
16:50:47 up 164 days, 2:06, 5 users, load average: 0.23, 0.20, 0.25
</pre>
</codesample>
^ permalink raw reply related [flat|nested] 30+ messages in thread
* [gentoo-commits] proj/devmanual:master commit in: appendices/devbook-guide/
@ 2020-01-15 21:29 Ulrich Müller
0 siblings, 0 replies; 30+ messages in thread
From: Ulrich Müller @ 2020-01-15 21:29 UTC (permalink / raw
To: gentoo-commits
commit: d10a853abe03569b235f960693f47960c494fd9b
Author: Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Sat Jan 11 10:10:07 2020 +0000
Commit: Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Wed Jan 15 21:28:45 2020 +0000
URL: https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=d10a853a
devbook-guide: Explain <codesample>.
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>
appendices/devbook-guide/text.xml | 69 ++++++++++++++++++++++++++++++++++++---
1 file changed, 65 insertions(+), 4 deletions(-)
diff --git a/appendices/devbook-guide/text.xml b/appendices/devbook-guide/text.xml
index 5ae077b..0f0a3ad 100644
--- a/appendices/devbook-guide/text.xml
+++ b/appendices/devbook-guide/text.xml
@@ -262,10 +262,71 @@ prose more <e>punch</e>!
<title>Code samples and colour-coding</title>
<body>
-<todo>
-Fill this section with the information about the use of
-<codesample/>.
-</todo>
+<p>
+The <c><pre></c> tag does not support any syntax highlighting. When you
+need syntax highlighting, use the <c><codesample></c> tag along with a
+<c>lang</c> attribute <d/> usually you want this to be set to <c>"ebuild"</c>
+to syntax highlight ebuild code snippets. Currently, the following languages
+are supported:
+</p>
+
+<ul>
+ <li>c</li>
+ <li>ebuild</li>
+ <li>make</li>
+ <li>m4</li>
+ <li>sgml</li>
+</ul>
+
+<note>
+Remember that all leading and trailing spaces, and line breaks in
+<c><codesample></c> blocks will appear in the displayed html page.
+</note>
+
+<p>
+Sample <c><codesample lang="c"></c> block:
+</p>
+
+<codesample lang="c">
+#include <stdio.h>
+
+main()
+{
+ /* This is a comment */
+ printf("Hello, world!\n");
+}
+</codesample>
+
+<p>
+You can also specify <c>numbering="lines"</c> to enable line numbering, as in
+the following example:
+</p>
+
+<codesample lang="ebuild" numbering="lines">
+# Copyright 1999-2020 Gentoo Authors
+# Distributed under the terms of the GNU General Public License v2
+
+EAPI=7
+
+DESCRIPTION="MicroGnuEmacs, a port from the BSDs"
+HOMEPAGE="https://homepage.boetes.org/software/mg/"
+SRC_URI="https://github.com/hboetes/${PN}/archive/${PV}.tar.gz -> ${P}.tar.gz"
+
+LICENSE="public-domain"
+SLOT="0"
+KEYWORDS="alpha amd64 arm hppa ppc ~ppc64 sparc x86"
+
+RDEPEND="sys-libs/ncurses:0=
+ >=dev-libs/libbsd-0.7.0"
+DEPEND="${RDEPEND}"
+BDEPEND="virtual/pkgconfig"
+
+src_install() {
+ dobin mg
+ doman mg.1
+ dodoc README tutorial
+}
+</codesample>
</body>
</subsection>
^ permalink raw reply related [flat|nested] 30+ messages in thread
* [gentoo-commits] proj/devmanual:master commit in: appendices/devbook-guide/
@ 2020-01-15 21:30 Ulrich Müller
0 siblings, 0 replies; 30+ messages in thread
From: Ulrich Müller @ 2020-01-15 21:30 UTC (permalink / raw
To: gentoo-commits
commit: 710b619980ed23811cbc0841466b9502a2c92278
Author: Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Wed Jan 15 21:09:28 2020 +0000
Commit: Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Wed Jan 15 21:28:47 2020 +0000
URL: https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=710b6199
devbook-guide: Rename from "GuideXML guide" to "DevBook XML guide".
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>
appendices/devbook-guide/text.xml | 34 +++++++++++++++++-----------------
1 file changed, 17 insertions(+), 17 deletions(-)
diff --git a/appendices/devbook-guide/text.xml b/appendices/devbook-guide/text.xml
index 1e73104..35ecace 100644
--- a/appendices/devbook-guide/text.xml
+++ b/appendices/devbook-guide/text.xml
@@ -1,16 +1,16 @@
<?xml version="1.0" encoding="UTF-8"?>
<guide self="appendices/devbook-guide/">
<chapter>
-<title>Gentoo GuideXML Guide</title>
+<title>Gentoo DevBook XML Guide</title>
<section>
-<title>GuideXML basics</title>
+<title>DevBook XML basics</title>
<subsection>
-<title>GuideXML design goals</title>
+<title>DevBook XML design goals</title>
<body>
<p>
-The guideXML syntax is lightweight yet expressive, so that it is easy to
+The DevBook XML syntax is lightweight yet expressive, so that it is easy to
learn yet also provides all the features we need for the creation of web
documentation. The number of tags is kept to a minimum <d/> just those we need.
This makes it easy to transform guide into other formats, such as DocBook
@@ -18,7 +18,7 @@ XML/SGML or web-ready HTML.
</p>
<p>
-The goal is to make it easy to <e>create</e> and <e>transform</e> guideXML
+The goal is to make it easy to <e>create</e> and <e>transform</e> DevBook XML
documents.
</p>
@@ -27,21 +27,21 @@ documents.
</section>
<section>
-<title>GuideXML</title>
+<title>Devbook XML</title>
<subsection>
<title>Basic structure</title>
<body>
<p>
-Let's start learning the GuideXML syntax. We'll start with the the initial
-tags used in a GuideXML document:
+Let's start learning the DevBook XML syntax. We'll start with the initial tags
+used in a DevBook XML document:
</p>
-<codesample lang="sgml"><!-- The initial part of a guide XML document -->
+<codesample lang="sgml"><!-- The initial part of a DevBook XML document -->
<?xml version="1.0" encoding="UTF-8"?>
<guide self="appendices/devbook-guide/">
<chapter>
-<title>Gentoo GuideXML Guide</title>
+<title>Gentoo DevBook XML Guide</title>
</codesample>
<p>
@@ -88,7 +88,7 @@ title. Here's an example section with a single subsection, consisting of a
paragraph:
</p>
-<codesample lang="sgml"><!-- Minimal guide example -->
+<codesample lang="sgml"><!-- Minimal DevBook example -->
<section>
<title>This is my section</title>
<subsection>
@@ -408,8 +408,8 @@ for adding images without captions, borders, etc.
<body>
<p>
-GuideXML 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>
+DevBook XML 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
@@ -495,7 +495,7 @@ admonitions. A definition list comprises:
<body>
<p>
-GuideXML makes it really easy to reference other parts of the document using
+DevBook XML makes it really easy to reference other parts of the document using
hyperlinks. You can create a link pointing to another chapter, like
<uri link="::ebuild-writing/file-format/">Ebuild File Format</uri>, by typing
<c><uri link="::ebuild-writing/file-format/">Ebuild File
@@ -544,8 +544,8 @@ Both sections are described next.
<body>
<p>
-<b>Newlines</b> must be placed immediately after <e>every</e>
-GuideXML-tag (both opening as closing), except for:
+<b>Newlines</b> must be placed immediately after <e>every</e> DevBook XML tag
+(both opening as closing), except for:
<c><version></c>, <c><date></c>, <c><title></c>,
<c><th></c>, <c><ti></c>,
<c><li></c>, <c><i></c>, <c><e></c>,
@@ -577,7 +577,7 @@ parent XML-tags are <c><tr></c> (from <c><table></c>),
<c><ul></c>, <c><ol></c> and <c><dl></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.
+DevBook XML documents.
</p>
<p>
^ permalink raw reply related [flat|nested] 30+ messages in thread
* [gentoo-commits] proj/devmanual:master commit in: appendices/devbook-guide/
@ 2020-01-15 21:30 Ulrich Müller
0 siblings, 0 replies; 30+ messages in thread
From: Ulrich Müller @ 2020-01-15 21:30 UTC (permalink / raw
To: gentoo-commits
commit: e01f0401b79a3de5a0bb29e98918ee72cef249c7
Author: Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Wed Jan 15 21:25:12 2020 +0000
Commit: Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Wed Jan 15 21:28:48 2020 +0000
URL: https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=e01f0401
devbook-guide: Update "Internal Coding Style" section.
Describe only the tags that are actually used in DevBook XML.
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>
appendices/devbook-guide/text.xml | 21 +++++++++++----------
1 file changed, 11 insertions(+), 10 deletions(-)
diff --git a/appendices/devbook-guide/text.xml b/appendices/devbook-guide/text.xml
index 35ecace..b14a2a7 100644
--- a/appendices/devbook-guide/text.xml
+++ b/appendices/devbook-guide/text.xml
@@ -546,11 +546,11 @@ Both sections are described next.
<p>
<b>Newlines</b> must be placed immediately after <e>every</e> DevBook XML tag
(both opening as closing), except for:
-<c><version></c>, <c><date></c>, <c><title></c>,
-<c><th></c>, <c><ti></c>,
-<c><li></c>, <c><i></c>, <c><e></c>,
-<c><uri></c>, <c><path></c>, <c><b></c>, <c><c></c>,
-<c><mail></c>.
+<c><title></c>,
+<c><th></c>, <c><ti></c>, <c><li></c>,
+<c><dt></c>, <c><dd></c>,
+<c><b></c>, <c><c></c>, <c><e></c>, <c><d/></c>,
+<c><uri></c>.
</p>
<p>
@@ -564,11 +564,12 @@ Both sections are described next.
<p>
<b>Word-wrapping</b> must be applied at 80 characters except inside
-<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.
+<c><pre></c> and <c><codesample></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> and <c><codesample></c> elements within 80 columns
+to help console users.
</p>
<p>
^ permalink raw reply related [flat|nested] 30+ messages in thread
* [gentoo-commits] proj/devmanual:master commit in: appendices/devbook-guide/
@ 2020-01-15 22:14 Ulrich Müller
0 siblings, 0 replies; 30+ messages in thread
From: Ulrich Müller @ 2020-01-15 22:14 UTC (permalink / raw
To: gentoo-commits
commit: 2cd4880c0d7f41313678e69367cdcb703b90c74e
Author: Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Wed Jan 15 22:14:04 2020 +0000
Commit: Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Wed Jan 15 22:14:04 2020 +0000
URL: https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=2cd4880c
devbook-guide: Typo.
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>
appendices/devbook-guide/text.xml | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/appendices/devbook-guide/text.xml b/appendices/devbook-guide/text.xml
index b14a2a7..5f084bb 100644
--- a/appendices/devbook-guide/text.xml
+++ b/appendices/devbook-guide/text.xml
@@ -557,7 +557,7 @@ Both sections are described next.
<b>Blank lines</b> must be placed immediately after <e>every</e>
<c><body></c> (opening tag only) and before <e>every</e>
<c><section></c>, <c><p></c>, <c><pre></c>,
-<c><codesample></c>, <c><figure;></c>, <c><table></c>,
+<c><codesample></c>, <c><figure></c>, <c><table></c>,
<c><ul></c>, <c><ol></c>, <c><dl></c>, <c><note></c>
<c><important></c> and <c><warning></c> (opening tags only).
</p>
^ permalink raw reply related [flat|nested] 30+ messages in thread
* [gentoo-commits] proj/devmanual:master commit in: appendices/devbook-guide/
@ 2020-01-15 22:36 Ulrich Müller
0 siblings, 0 replies; 30+ messages in thread
From: Ulrich Müller @ 2020-01-15 22:36 UTC (permalink / raw
To: gentoo-commits
commit: 75a0de8654435df5ca5b12b2670e24258d30ffc9
Author: Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Wed Jan 15 22:35:17 2020 +0000
Commit: Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Wed Jan 15 22:35:17 2020 +0000
URL: https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=75a0de86
devbook-guide: Remove obsolete text in "<uri>" subsection.
Linking to other parts of the Gentoo web site doesn't apply to us,
because the devmanual isn't at www.gentoo.org.
Consistently have a trailing slash in example URIs.
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>
appendices/devbook-guide/text.xml | 16 +++++-----------
1 file changed, 5 insertions(+), 11 deletions(-)
diff --git a/appendices/devbook-guide/text.xml b/appendices/devbook-guide/text.xml
index 5f084bb..9b7a0c3 100644
--- a/appendices/devbook-guide/text.xml
+++ b/appendices/devbook-guide/text.xml
@@ -163,7 +163,7 @@ an example <c><body></c> element:
<codesample lang="sgml"><!-- Example of a body element -->
<p>
This is a paragraph. <c>/etc/passwd</c> is a file.
-<uri>https://forums.gentoo.org</uri> is my favorite website.
+<uri>https://forums.gentoo.org/</uri> is my favorite website.
Type <c>ls</c> if you feel like it. I <e>really</e> want to go to sleep now.
</p>
@@ -196,7 +196,7 @@ Now, here's how the <c><body></c> element above is rendered:
<p>
This is a paragraph. <c>/etc/passwd</c> is a file.
-<uri>https://forums.gentoo.org</uri> is my favorite web site.
+<uri>https://forums.gentoo.org/</uri> is my favorite web site.
Type <c>ls</c> if you feel like it. I <e>really</e> want to go to sleep now.
</p>
@@ -370,13 +370,7 @@ displayed in the body text, such as this link to
when you want to associate a URI with some other text <d/> for example,
<uri link="https://forums.gentoo.org/">the Gentoo Forums</uri>. To create
<e>this</e> link, I typed <c><uri link="https://forums.gentoo.org/">the
-Gentoo Forums</uri></c>. You don't need to write
-<c>https://www.gentoo.org/</c> to link to other parts of the Gentoo web site.
-For instance, a link to the <uri link="/doc/en/">documentation main index</uri>
-should be simply <c><uri link="/doc/en/index.xml">documentation main
-index</uri></c>. You can even omit <c>index.xml</c> when you link to a
-directory index, e.g. <c><uri link="/doc/en/">documentation main
-index</uri></c>. Leaving the trailing slash saves an extra HTTP request.
+Gentoo Forums</uri></c>.
</p>
<p>
@@ -649,8 +643,8 @@ with a capital letter.
<p>
Try to use <c><uri></c> with the <c>link</c> attribute as much as
-possible. In other words, the <uri link="https://forums.gentoo.org">Gentoo
-Forums</uri> is preferred over <uri>https://forums.gentoo.org</uri>.
+possible. In other words, the <uri link="https://forums.gentoo.org/">Gentoo
+Forums</uri> is preferred over <uri>https://forums.gentoo.org/</uri>.
</p>
</body>
^ permalink raw reply related [flat|nested] 30+ messages in thread
* [gentoo-commits] proj/devmanual:master commit in: appendices/devbook-guide/
@ 2020-01-16 18:50 Ulrich Müller
0 siblings, 0 replies; 30+ messages in thread
From: Ulrich Müller @ 2020-01-16 18:50 UTC (permalink / raw
To: gentoo-commits
commit: 81df8e36aeecf7234cd669ae593d1b5731cc01c5
Author: Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Thu Jan 16 18:44:20 2020 +0000
Commit: Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Thu Jan 16 18:44:20 2020 +0000
URL: https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=81df8e36
devbook-guide: Drop redundant subsection levels.
Guide XML allowed body elements only at the lowest section level.
DevBook XML doesn't have that strict rule, therefore we can drop
the unnecessary intermediate levels.
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>
appendices/devbook-guide/text.xml | 7 +------
1 file changed, 1 insertion(+), 6 deletions(-)
diff --git a/appendices/devbook-guide/text.xml b/appendices/devbook-guide/text.xml
index 9b7a0c3..66f85c2 100644
--- a/appendices/devbook-guide/text.xml
+++ b/appendices/devbook-guide/text.xml
@@ -4,8 +4,6 @@
<title>Gentoo DevBook XML Guide</title>
<section>
-<title>DevBook XML basics</title>
-<subsection>
<title>DevBook XML design goals</title>
<body>
@@ -23,7 +21,6 @@ documents.
</p>
</body>
-</subsection>
</section>
<section>
@@ -515,8 +512,6 @@ I could have written the two examples above in more compact form:
<section>
<title>Coding Style</title>
-<subsection>
-<title>Introduction</title>
<body>
<p>
@@ -532,7 +527,7 @@ Both sections are described next.
</p>
</body>
-</subsection>
+
<subsection>
<title>Internal Coding Style</title>
<body>
^ permalink raw reply related [flat|nested] 30+ messages in thread
* [gentoo-commits] proj/devmanual:master commit in: appendices/devbook-guide/
@ 2020-01-28 5:55 Ulrich Müller
0 siblings, 0 replies; 30+ messages in thread
From: Ulrich Müller @ 2020-01-28 5:55 UTC (permalink / raw
To: gentoo-commits
commit: e4018d0bb607ec164871ab536b2334507f46f069
Author: Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Tue Jan 28 05:54:30 2020 +0000
Commit: Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Tue Jan 28 05:54:30 2020 +0000
URL: https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=e4018d0b
appendices/devbook-guide: Fix misplaced parentheses.
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>
appendices/devbook-guide/text.xml | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/appendices/devbook-guide/text.xml b/appendices/devbook-guide/text.xml
index 66f85c2..72e51e9 100644
--- a/appendices/devbook-guide/text.xml
+++ b/appendices/devbook-guide/text.xml
@@ -114,7 +114,7 @@ at the tags that are allowed inside a <c><body></c> element in a bit.
<note>
The <c><chapter></c>, <c><section></c>, <c><subsection></c>
-and <c><subsubsection></c>) elements contain a <c><body></c> and/or
+and <c><subsubsection></c> elements contain a <c><body></c> and/or
any number of section elements of the next lower level. Skipping of levels is
not allowed, e.g., a subsection cannot be directly below a chapter.
</note>
@@ -619,7 +619,7 @@ Correct: <uri link="https://forums.gentoo.org/">
<p>
Inside tables (<c><table></c>) and listings (<c><ul></c>,
-<c><ol></c>) and <c><dl></c>, periods (".") should not be used
+<c><ol></c> and <c><dl></c>), periods (".") should not be used
unless multiple sentences are used. In that case, every sentence should end
with a period (or other reading marks).
</p>
^ permalink raw reply related [flat|nested] 30+ messages in thread
* [gentoo-commits] proj/devmanual:master commit in: appendices/devbook-guide/
@ 2020-02-22 21:27 Ulrich Müller
0 siblings, 0 replies; 30+ messages in thread
From: Ulrich Müller @ 2020-02-22 21:27 UTC (permalink / raw
To: gentoo-commits
commit: 8bd0dfe59f40e09049e7fc86cb59da2aa51e1ee0
Author: Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Sat Feb 22 21:25:47 2020 +0000
Commit: Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Sat Feb 22 21:25:47 2020 +0000
URL: https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=8bd0dfe5
appendices/devbook-guide: Sync source and rendered code.
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>
appendices/devbook-guide/text.xml | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/appendices/devbook-guide/text.xml b/appendices/devbook-guide/text.xml
index 1a3d538..212b637 100644
--- a/appendices/devbook-guide/text.xml
+++ b/appendices/devbook-guide/text.xml
@@ -503,7 +503,7 @@ I could have written the two examples above in more compact form:
<c><uri link="::ebuild-writing/file-format/"/></c> and
<c><uri link="::quickstart/#First Ebuild"/></c> render as
<uri link="::ebuild-writing/file-format/"/> and
-<uri link="::quickstart#First Ebuild"/>, respectively.
+<uri link="::quickstart/#First Ebuild"/>, respectively.
</p>
</body>
^ permalink raw reply related [flat|nested] 30+ messages in thread
* [gentoo-commits] proj/devmanual:master commit in: appendices/devbook-guide/
@ 2020-03-01 12:32 Ulrich Müller
0 siblings, 0 replies; 30+ messages in thread
From: Ulrich Müller @ 2020-03-01 12:32 UTC (permalink / raw
To: gentoo-commits
commit: 7b57dc9b70fec1d7c38c7a160e7f90b0e1063d89
Author: Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Sun Mar 1 12:30:00 2020 +0000
Commit: Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Sun Mar 1 12:30:00 2020 +0000
URL: https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=7b57dc9b
devbook-guide: Flip order of <important> and <warning> examples.
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>
appendices/devbook-guide/text.xml | 16 ++++++++--------
1 file changed, 8 insertions(+), 8 deletions(-)
diff --git a/appendices/devbook-guide/text.xml b/appendices/devbook-guide/text.xml
index 212b637..26de10e 100644
--- a/appendices/devbook-guide/text.xml
+++ b/appendices/devbook-guide/text.xml
@@ -178,13 +178,13 @@ Make HTML/XML easier to read by using selective emphasis:
This is a note.
</note>
-<warning>
-This is a warning.
-</warning>
-
<important>
This is important.
</important>
+
+<warning>
+This is a warning.
+</warning>
</codesample>
<p>
@@ -211,14 +211,14 @@ Make HTML/XML easier to read by using selective emphasis:
This is a note.
</note>
-<warning>
-This is a warning.
-</warning>
-
<important>
This is important.
</important>
+<warning>
+This is a warning.
+</warning>
+
</body>
</subsection>
<subsection>
^ permalink raw reply related [flat|nested] 30+ messages in thread
* [gentoo-commits] proj/devmanual:master commit in: appendices/devbook-guide/
@ 2020-03-06 16:30 Ulrich Müller
0 siblings, 0 replies; 30+ messages in thread
From: Ulrich Müller @ 2020-03-06 16:30 UTC (permalink / raw
To: gentoo-commits
commit: 92a1cf4b1f924f00d2a0eaa5d2e01f9bf404aad9
Author: Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Fri Mar 6 16:24:37 2020 +0000
Commit: Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Fri Mar 6 16:24:37 2020 +0000
URL: https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=92a1cf4b
devbook-guide: Use consistent ordering when mentioning admonitions.
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>
appendices/devbook-guide/text.xml | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/appendices/devbook-guide/text.xml b/appendices/devbook-guide/text.xml
index 51e8a8d..a7d9eef 100644
--- a/appendices/devbook-guide/text.xml
+++ b/appendices/devbook-guide/text.xml
@@ -229,7 +229,7 @@ This is a warning.
We introduced a lot of new tags in the previous section <d/> here's what you
need to know. The <c><p></c> (paragraph), <c><pre></c>
(preformatted block), <c><codesample></c> (code block),
-<c><note></c>, <c><warning></c> and <c><important></c> tags
+<c><note></c>, <c><important></c> and <c><warning></c> tags
all can contain one or more lines of text. Besides the <c><figure></c>,
<c><table></c>, <c><ul></c>, <c><ol></c>
and <c><dl></c> elements (which we'll cover in just a bit), these are the
@@ -577,7 +577,7 @@ Both sections are described next.
<c><body></c> (opening tag only) and before <e>every</e>
<c><section></c>, <c><p></c>, <c><pre></c>,
<c><codesample></c>, <c><figure></c>, <c><table></c>,
-<c><ul></c>, <c><ol></c>, <c><dl></c>, <c><note></c>
+<c><ul></c>, <c><ol></c>, <c><dl></c>, <c><note></c>,
<c><important></c> and <c><warning></c> (opening tags only).
</p>
^ permalink raw reply related [flat|nested] 30+ messages in thread
* [gentoo-commits] proj/devmanual:master commit in: appendices/devbook-guide/
@ 2020-03-06 16:30 Ulrich Müller
0 siblings, 0 replies; 30+ messages in thread
From: Ulrich Müller @ 2020-03-06 16:30 UTC (permalink / raw
To: gentoo-commits
commit: d7fd191af16b7ebe32ea13d5bef2c7ef1f0da538
Author: Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Fri Mar 6 16:23:33 2020 +0000
Commit: Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Fri Mar 6 16:23:33 2020 +0000
URL: https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=d7fd191a
devbook-guide: Restore example for nested lists.
This partially reverts commit 491304c.
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>
appendices/devbook-guide/text.xml | 40 ++++++++++++++++++++++++++++++++++-----
1 file changed, 35 insertions(+), 5 deletions(-)
diff --git a/appendices/devbook-guide/text.xml b/appendices/devbook-guide/text.xml
index 26de10e..51e8a8d 100644
--- a/appendices/devbook-guide/text.xml
+++ b/appendices/devbook-guide/text.xml
@@ -465,18 +465,48 @@ that you must close all tags including list items unlike in HTML.
<p>
Definition lists (<c><dl></c>) are also supported. Please note that
-neither the definition term tag (<c><dt></c>) nor the definition data tag
-(<c><dd></c>) accept any other block level tag such as paragraphs or
-admonitions. A definition list comprises:
+the definition term tag (<c><dt></c>) does not accept any other block
+level tag such as paragraphs or admonitions. A definition list comprises:
</p>
<dl>
<dt><c><dl></c></dt>
<dd>A <b>D</b>efinition <b>L</b>ist Tag containing</dd>
<dt><c><dt></c></dt>
- <dd><b>D</b>efinition <b>T</b>erm Tags,</dd>
+ <dd><b>D</b>efinition <b>T</b>erm Tags</dd>
<dt><c><dd></c></dt>
- <dd>each followed by one or more <b>D</b>efinition <b>D</b>ata Tags.</dd>
+ <dd>and <b>D</b>efinition <b>D</b>ata Tags.</dd>
+</dl>
+
+<p>
+The following example copied from
+<uri link="https://www.w3.org/TR/REC-html40/struct/lists.html">w3.org</uri>
+shows that lists may also be nested and different list types may be used
+together:
+</p>
+
+<dl>
+ <dt>The ingredients:</dt>
+ <dd>
+ <ul>
+ <li>100 g flour</li>
+ <li>10 g sugar</li>
+ <li>1 cup water</li>
+ <li>2 eggs</li>
+ <li>salt, pepper</li>
+ </ul>
+ </dd>
+ <dt>The procedure:</dt>
+ <dd>
+ <ol>
+ <li>Mix dry ingredients thoroughly.</li>
+ <li>Pour in wet ingredients.</li>
+ <li>Mix for 10 minutes.</li>
+ <li>Bake for one hour at 300 degrees.</li>
+ </ol>
+ </dd>
+ <dt>Notes:</dt>
+ <dd>The recipe may be improved by adding raisins.</dd>
</dl>
</body>
^ permalink raw reply related [flat|nested] 30+ messages in thread
* [gentoo-commits] proj/devmanual:master commit in: appendices/devbook-guide/
@ 2020-08-21 16:53 Ulrich Müller
0 siblings, 0 replies; 30+ messages in thread
From: Ulrich Müller @ 2020-08-21 16:53 UTC (permalink / raw
To: gentoo-commits
commit: 786b3696c9b2f4bc57b28be30dda63c75a6fe59b
Author: Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Tue Aug 4 15:56:00 2020 +0000
Commit: Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Fri Aug 21 16:49:24 2020 +0000
URL: https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=786b3696
devbook-guide: Opening tags should not be split between lines.
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>
appendices/devbook-guide/text.xml | 6 ++++++
1 file changed, 6 insertions(+)
diff --git a/appendices/devbook-guide/text.xml b/appendices/devbook-guide/text.xml
index a7d9eef..a0948d5 100644
--- a/appendices/devbook-guide/text.xml
+++ b/appendices/devbook-guide/text.xml
@@ -631,6 +631,12 @@ An example for indentation is:
</ul>
</codesample>
+<p>
+<b>Opening tags</b> with a single attribute may not be split between lines.
+For example, don't put a newline between <c><uri</c> and its <c>link</c>
+attribute. Break the line before the <c><uri></c> tag instead.
+</p>
+
<p>
<b>Attributes</b> may not have spaces in between the attribute, the "=" mark,
and the attribute value. As an example:
^ permalink raw reply related [flat|nested] 30+ messages in thread
* [gentoo-commits] proj/devmanual:master commit in: appendices/devbook-guide/
@ 2020-12-14 19:35 Ulrich Müller
0 siblings, 0 replies; 30+ messages in thread
From: Ulrich Müller @ 2020-12-14 19:35 UTC (permalink / raw
To: gentoo-commits
commit: e9fa4f2fc58a9605a0f1b1e92dd01601452a5d92
Author: Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Mon Dec 14 19:26:53 2020 +0000
Commit: Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Mon Dec 14 19:26:53 2020 +0000
URL: https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=e9fa4f2f
devbook-guide: Restore original example.
Linking to www.gentoo.org is no longer special, therefore we can
restore the original example, i.e., partially revert this commit:
https://sources.gentoo.org/cgi-bin/viewvc.cgi/gentoo/xml/htdocs/doc/en/xml-guide.xml?revision=1.35&view=markup
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>
appendices/devbook-guide/text.xml | 23 ++++++++++++-----------
1 file changed, 12 insertions(+), 11 deletions(-)
diff --git a/appendices/devbook-guide/text.xml b/appendices/devbook-guide/text.xml
index a0948d5..1924843 100644
--- a/appendices/devbook-guide/text.xml
+++ b/appendices/devbook-guide/text.xml
@@ -160,7 +160,7 @@ an example <c><body></c> element:
<codesample lang="sgml"><!-- Example of a body element -->
<p>
This is a paragraph. <c>/etc/passwd</c> is a file.
-<uri>https://forums.gentoo.org/</uri> is my favorite website.
+<uri>https://www.gentoo.org/</uri> is my favorite website.
Type <c>ls</c> if you feel like it. I <e>really</e> want to go to sleep now.
</p>
@@ -193,7 +193,7 @@ Now, here's how the <c><body></c> element above is rendered:
<p>
This is a paragraph. <c>/etc/passwd</c> is a file.
-<uri>https://forums.gentoo.org/</uri> is my favorite web site.
+<uri>https://www.gentoo.org/</uri> is my favorite web site.
Type <c>ls</c> if you feel like it. I <e>really</e> want to go to sleep now.
</p>
@@ -362,12 +362,12 @@ src_install() {
The <c><uri></c> tag is used to point to files/locations on the Internet.
It has two forms <d/> the first can be used when you want to have the actual URI
displayed in the body text, such as this link to
-<uri>https://forums.gentoo.org/</uri>. To create this link, I typed
-<c><uri>https://forums.gentoo.org/</uri></c>. The alternate form is
+<uri>https://www.gentoo.org/</uri>. To create this link, I typed
+<c><uri>https://www.gentoo.org/</uri></c>. The alternate form is
when you want to associate a URI with some other text <d/> for example,
-<uri link="https://forums.gentoo.org/">the Gentoo Forums</uri>. To create
-<e>this</e> link, I typed <c><uri link="https://forums.gentoo.org/">the
-Gentoo Forums</uri></c>.
+<uri link="https://www.gentoo.org/">the Gentoo Linux website</uri>. To create
+<e>this</e> link, I typed <c><uri link="https://www.gentoo.org/">the
+Gentoo Linux website</uri></c>.
</p>
<p>
@@ -643,8 +643,8 @@ and the attribute value. As an example:
</p>
<codesample lang="sgml"><!-- Attributes -->
-Wrong : <uri link = "https://forums.gentoo.org/">
-Correct: <uri link="https://forums.gentoo.org/">
+Wrong : <uri link = "https://www.gentoo.org/">
+Correct: <uri link="https://www.gentoo.org/">
</codesample>
</body>
@@ -674,8 +674,9 @@ with a capital letter.
<p>
Try to use <c><uri></c> with the <c>link</c> attribute as much as
-possible. In other words, the <uri link="https://forums.gentoo.org/">Gentoo
-Forums</uri> is preferred over <uri>https://forums.gentoo.org/</uri>.
+possible. In other words, the
+<uri link="https://www.gentoo.org/">Gentoo website</uri> is preferred over
+<uri>https://www.gentoo.org/</uri>.
</p>
</body>
^ permalink raw reply related [flat|nested] 30+ messages in thread
* [gentoo-commits] proj/devmanual:master commit in: appendices/devbook-guide/
@ 2021-03-11 11:24 Ulrich Müller
0 siblings, 0 replies; 30+ messages in thread
From: Ulrich Müller @ 2021-03-11 11:24 UTC (permalink / raw
To: gentoo-commits
commit: 0099daa4739d635a7ab455450d531747b0f508d8
Author: Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Thu Mar 11 11:24:03 2021 +0000
Commit: Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Thu Mar 11 11:24:03 2021 +0000
URL: https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=0099daa4
devbook-guide: Fix typo
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>
appendices/devbook-guide/text.xml | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/appendices/devbook-guide/text.xml b/appendices/devbook-guide/text.xml
index d37bbce..8b3f80c 100644
--- a/appendices/devbook-guide/text.xml
+++ b/appendices/devbook-guide/text.xml
@@ -564,7 +564,7 @@ Both sections are described next.
<p>
<b>Newlines</b> must be placed immediately after <e>every</e> DevBook XML tag
-(both opening as closing), except for:
+(both opening and closing), except for:
<c><title></c>,
<c><th></c>, <c><ti></c>, <c><li></c>,
<c><dt></c>, <c><dd></c>,
^ permalink raw reply related [flat|nested] 30+ messages in thread
* [gentoo-commits] proj/devmanual:master commit in: appendices/devbook-guide/
@ 2021-03-12 19:32 Ulrich Müller
0 siblings, 0 replies; 30+ messages in thread
From: Ulrich Müller @ 2021-03-12 19:32 UTC (permalink / raw
To: gentoo-commits
commit: e554a3737446e302bfc7224c434c3719c554c950
Author: Sam James <sam <AT> gentoo <DOT> org>
AuthorDate: Fri Mar 12 18:23:49 2021 +0000
Commit: Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Fri Mar 12 19:32:21 2021 +0000
URL: https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=e554a373
appendices/devbook-guide: fix formatting phase definition
Signed-off-by: Sam James <sam <AT> gentoo.org>
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>
appendices/devbook-guide/text.xml | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/appendices/devbook-guide/text.xml b/appendices/devbook-guide/text.xml
index 8b3f80c..b98910f 100644
--- a/appendices/devbook-guide/text.xml
+++ b/appendices/devbook-guide/text.xml
@@ -345,7 +345,7 @@ RDEPEND="sys-libs/ncurses:0=
DEPEND="${RDEPEND}"
BDEPEND="virtual/pkgconfig"
-src_install() {
+src_install() {
dobin mg
doman mg.1
dodoc README tutorial
^ permalink raw reply related [flat|nested] 30+ messages in thread
* [gentoo-commits] proj/devmanual:master commit in: appendices/devbook-guide/
@ 2021-03-19 19:22 Ulrich Müller
0 siblings, 0 replies; 30+ messages in thread
From: Ulrich Müller @ 2021-03-19 19:22 UTC (permalink / raw
To: gentoo-commits
commit: 7a84ee5d396486e897e3916022738b35de54ab6f
Author: Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Sun Mar 7 17:07:01 2021 +0000
Commit: Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Fri Mar 19 19:19:08 2021 +0000
URL: https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=7a84ee5d
devbook-guide: Document that tabs in pre and codesample are allowed
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>
appendices/devbook-guide/text.xml | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/appendices/devbook-guide/text.xml b/appendices/devbook-guide/text.xml
index b98910f..bf9e50a 100644
--- a/appendices/devbook-guide/text.xml
+++ b/appendices/devbook-guide/text.xml
@@ -597,7 +597,7 @@ parent XML-tags are <c><tr></c> (from <c><table></c>),
<c><ul></c>, <c><ol></c> and <c><dl></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
-DevBook XML documents.
+DevBook XML documents (again, except for <pre> and <codesample>).
</p>
<p>
^ permalink raw reply related [flat|nested] 30+ messages in thread
* [gentoo-commits] proj/devmanual:master commit in: appendices/devbook-guide/
@ 2021-03-19 19:23 Ulrich Müller
0 siblings, 0 replies; 30+ messages in thread
From: Ulrich Müller @ 2021-03-19 19:23 UTC (permalink / raw
To: gentoo-commits
commit: 621fa0991832f3eb80cf0ab26e55a2ba112fc53a
Author: Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Fri Mar 12 17:41:53 2021 +0000
Commit: Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Fri Mar 19 19:19:39 2021 +0000
URL: https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=621fa099
devbook-guide: Move all inline elements together
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>
appendices/devbook-guide/text.xml | 114 +++++++++++++++++++-------------------
1 file changed, 57 insertions(+), 57 deletions(-)
diff --git a/appendices/devbook-guide/text.xml b/appendices/devbook-guide/text.xml
index bf9e50a..28fbacd 100644
--- a/appendices/devbook-guide/text.xml
+++ b/appendices/devbook-guide/text.xml
@@ -247,39 +247,6 @@ preserve their whitespace exactly, making them well-suited for code excerpts:
</pre>
</codesample>
-</body>
-</subsection>
-<subsection>
-<title><c>, <b>, and <e></title>
-<body>
-
-<p>
-The <c><c></c> element is used to mark up a <e>command</e> or <e>user
-input</e>. Think of <c><c></c> as a way to alert the reader to something
-that they can type in that will perform some kind of action. For example, all
-the XML tags displayed in this document are enclosed in a <c><c></c>
-element because they represent something that the user could type in that is
-not a path. By using <c><c></c> elements, you'll help your readers
-quickly identify commands that they need to type in. Also, because
-<c><c></c> elements are already offset from regular text, <e>it is rarely
-necessary to surround user input with double-quotes</e>. For example, don't
-refer to a "<c><c></c>" element like I did in this sentence. Avoiding
-the use of unnecessary double-quotes makes a document more readable <d/> and
-adorable!
-</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
-prose more <e>punch</e>!
-</p>
-
</body>
</subsection>
<subsection>
@@ -352,30 +319,6 @@ src_install() {
}
</codesample>
-</body>
-</subsection>
-<subsection>
-<title><uri></title>
-<body>
-
-<p>
-The <c><uri></c> tag is used to point to files/locations on the Internet.
-It has two forms <d/> the first can be used when you want to have the actual URI
-displayed in the body text, such as this link to
-<uri>https://www.gentoo.org/</uri>. To create this link, I typed
-<c><uri>https://www.gentoo.org/</uri></c>. The alternate form is
-when you want to associate a URI with some other text <d/> for example,
-<uri link="https://www.gentoo.org/">the Gentoo Linux website</uri>. To create
-<e>this</e> link, I typed <c><uri link="https://www.gentoo.org/">the
-Gentoo Linux website</uri></c>.
-</p>
-
-<p>
-Please avoid the <uri link="https://en.wikipedia.org/wiki/Click_here">click here
-syndrome</uri> as recommended by the <uri
-link="https://www.w3.org/QA/Tips/noClickHere">W3C</uri>.
-</p>
-
</body>
</subsection>
<subsection>
@@ -509,6 +452,63 @@ together:
<dd>The recipe may be improved by adding raisins.</dd>
</dl>
+</body>
+</subsection>
+<subsection>
+<title><c>, <b>, and <e></title>
+<body>
+
+<p>
+The <c><c></c> element is used to mark up a <e>command</e> or <e>user
+input</e>. Think of <c><c></c> as a way to alert the reader to something
+that they can type in that will perform some kind of action. For example,
+all the XML tags displayed in this document are enclosed in a <c><c></c>
+element because they represent something that the user could type in that is
+not a path. By using <c><c></c> elements, you'll help your readers
+quickly identify commands that they need to type in. Also, because
+<c><c></c> elements are already offset from regular text, <e>it is rarely
+necessary to surround user input with double-quotes</e>. For example, don't
+refer to a "<c><c></c>" element like I did in this sentence. Avoiding
+the use of unnecessary double-quotes makes a document more readable <d/> and
+adorable!
+</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
+prose more <e>punch</e>!
+</p>
+
+</body>
+</subsection>
+<subsection>
+<title><uri></title>
+<body>
+
+<p>
+The <c><uri></c> tag is used to point to files/locations on the Internet.
+It has two forms <d/> the first can be used when you want to have the actual
+URI displayed in the body text, such as this link to
+<uri>https://www.gentoo.org/</uri>. To create this link, I typed
+<c><uri>https://www.gentoo.org/</uri></c>. The alternate form is
+when you want to associate a URI with some other text <d/> for example,
+<uri link="https://www.gentoo.org/">the Gentoo Linux website</uri>. To create
+<e>this</e> link, I typed <c><uri link="https://www.gentoo.org/">the
+Gentoo Linux website</uri></c>.
+</p>
+
+<p>
+Please avoid the <uri link="https://en.wikipedia.org/wiki/Click_here">click
+here syndrome</uri> as recommended by the
+<uri link="https://www.w3.org/QA/Tips/noClickHere">W3C</uri>.
+</p>
+
</body>
</subsection>
<subsection>
^ permalink raw reply related [flat|nested] 30+ messages in thread
* [gentoo-commits] proj/devmanual:master commit in: appendices/devbook-guide/
@ 2021-03-19 19:23 Ulrich Müller
0 siblings, 0 replies; 30+ messages in thread
From: Ulrich Müller @ 2021-03-19 19:23 UTC (permalink / raw
To: gentoo-commits
commit: 91b323cd575dff579191a767190e9d56ff255d44
Author: Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Fri Mar 12 17:51:37 2021 +0000
Commit: Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Fri Mar 19 19:19:39 2021 +0000
URL: https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=91b323cd
devbook-guide: Clearer section structure
Drop the "Devbook XML" section header which was not very useful.
Instead, promote "Basic structure" from subsection to section,
and introduce two new sections "Body elements" and "Inline elements".
So, the resulting section structure is:
DevBook XML design goals
Basic structure
Sections and subsections
Including sub-documents
An example <body>
Body elements
Code samples and colour-coding
Figures
Tables
Lists
Inline elements
<c>, <b>, and <e>
<uri>
Intra-document references
Coding Style
Internal Coding Style
External Coding Style
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>
appendices/devbook-guide/text.xml | 16 ++++++++++------
1 file changed, 10 insertions(+), 6 deletions(-)
diff --git a/appendices/devbook-guide/text.xml b/appendices/devbook-guide/text.xml
index 28fbacd..64d1178 100644
--- a/appendices/devbook-guide/text.xml
+++ b/appendices/devbook-guide/text.xml
@@ -24,8 +24,6 @@ documents.
</section>
<section>
-<title>Devbook XML</title>
-<subsection>
<title>Basic structure</title>
<body>
@@ -71,7 +69,7 @@ All tags must be closed of course, so the document ends with:
</codesample>
</body>
-</subsection>
+
<subsection>
<title>Sections and subsections</title>
<body>
@@ -221,8 +219,10 @@ This is a warning.
</body>
</subsection>
-<subsection>
-<title>The <body> tags</title>
+</section>
+
+<section>
+<title>Body elements</title>
<body>
<p>
@@ -248,7 +248,7 @@ preserve their whitespace exactly, making them well-suited for code excerpts:
</codesample>
</body>
-</subsection>
+
<subsection>
<title>Code samples and colour-coding</title>
<body>
@@ -454,6 +454,10 @@ together:
</body>
</subsection>
+</section>
+
+<section>
+<title>Inline elements</title>
<subsection>
<title><c>, <b>, and <e></title>
<body>
^ permalink raw reply related [flat|nested] 30+ messages in thread
* [gentoo-commits] proj/devmanual:master commit in: appendices/devbook-guide/
@ 2021-07-31 17:59 Ulrich Müller
0 siblings, 0 replies; 30+ messages in thread
From: Ulrich Müller @ 2021-07-31 17:59 UTC (permalink / raw
To: gentoo-commits
commit: 2b798b92188375840ed1273bc1373ca1eb1f0f69
Author: Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Sat Jul 31 08:23:35 2021 +0000
Commit: Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Sat Jul 31 08:32:03 2021 +0000
URL: https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=2b798b92
devbook-guide: Remove warning about newlines in title element
Apparently the underlying bug has been fixed in commit b5bfc69.
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>
appendices/devbook-guide/text.xml | 5 -----
1 file changed, 5 deletions(-)
diff --git a/appendices/devbook-guide/text.xml b/appendices/devbook-guide/text.xml
index 64d1178..e233e21 100644
--- a/appendices/devbook-guide/text.xml
+++ b/appendices/devbook-guide/text.xml
@@ -54,11 +54,6 @@ one chapter. Its <c><title></c> is used to set the title for the entire
document.
</p>
-<important>
-The <c><title></c> element cannot contain any newlines. Make sure it is
-in one line, including its opening and closing tags.
-</important>
-
<p>
All tags must be closed of course, so the document ends with:
</p>
^ permalink raw reply related [flat|nested] 30+ messages in thread
* [gentoo-commits] proj/devmanual:master commit in: appendices/devbook-guide/
@ 2022-02-16 18:56 Ulrich Müller
0 siblings, 0 replies; 30+ messages in thread
From: Ulrich Müller @ 2022-02-16 18:56 UTC (permalink / raw
To: gentoo-commits
commit: ece9a5736c0a04daa7d03738a9b2624f088f85fa
Author: Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Wed Feb 16 18:54:40 2022 +0000
Commit: Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Wed Feb 16 18:54:40 2022 +0000
URL: https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=ece9a573
appendices/devbook-guide: Indent the table properly
The style guide should follow the style guide. :)
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>
appendices/devbook-guide/text.xml | 52 +++++++++++++++++++--------------------
1 file changed, 26 insertions(+), 26 deletions(-)
diff --git a/appendices/devbook-guide/text.xml b/appendices/devbook-guide/text.xml
index e233e21..f9a6b5a 100644
--- a/appendices/devbook-guide/text.xml
+++ b/appendices/devbook-guide/text.xml
@@ -359,32 +359,32 @@ right-aligned, left-aligned or centered with the <c>align</c> attribute.
</p>
<table>
- <tr>
- <th align="center" colspan="4">This title spans 4 columns</th>
- </tr>
- <tr>
- <th rowspan="6">This title spans 6 rows</th>
- <ti>Item A1</ti>
- <ti>Item A2</ti>
- <ti>Item A3</ti>
- </tr>
- <tr>
- <ti align="center">Item B1</ti>
- <th colspan="2" rowspan="2" align="right">Blocky 2x2 title</th>
- </tr>
- <tr>
- <ti align="right">Item C1</ti>
- </tr>
- <tr>
- <ti colspan="3" align="center">Item D1..D3</ti>
- </tr>
- <tr>
- <ti rowspan="2">Item E1..F1</ti>
- <ti colspan="2" align="right">Item E2..E3</ti>
- </tr>
- <tr>
- <ti colspan="2" align="right">Item F2..F3</ti>
- </tr>
+<tr>
+ <th align="center" colspan="4">This title spans 4 columns</th>
+</tr>
+<tr>
+ <th rowspan="6">This title spans 6 rows</th>
+ <ti>Item A1</ti>
+ <ti>Item A2</ti>
+ <ti>Item A3</ti>
+</tr>
+<tr>
+ <ti align="center">Item B1</ti>
+ <th colspan="2" rowspan="2" align="right">Blocky 2x2 title</th>
+</tr>
+<tr>
+ <ti align="right">Item C1</ti>
+</tr>
+<tr>
+ <ti colspan="3" align="center">Item D1..D3</ti>
+</tr>
+<tr>
+ <ti rowspan="2">Item E1..F1</ti>
+ <ti colspan="2" align="right">Item E2..E3</ti>
+</tr>
+<tr>
+ <ti colspan="2" align="right">Item F2..F3</ti>
+</tr>
</table>
</body>
^ permalink raw reply related [flat|nested] 30+ messages in thread
* [gentoo-commits] proj/devmanual:master commit in: appendices/devbook-guide/
@ 2023-10-05 20:29 Ulrich Müller
0 siblings, 0 replies; 30+ messages in thread
From: Ulrich Müller @ 2023-10-05 20:29 UTC (permalink / raw
To: gentoo-commits
commit: acbf1e23650c3cad83ed0d39980032dcb885f7e7
Author: Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Thu Oct 5 20:29:19 2023 +0000
Commit: Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Thu Oct 5 20:29:19 2023 +0000
URL: https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=acbf1e23
appendices/devbook-guide: GuideXML -> DevBook XML
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>
appendices/devbook-guide/text.xml | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/appendices/devbook-guide/text.xml b/appendices/devbook-guide/text.xml
index f9a6b5a..7c12d6d 100644
--- a/appendices/devbook-guide/text.xml
+++ b/appendices/devbook-guide/text.xml
@@ -11,7 +11,7 @@
The DevBook XML syntax is lightweight yet expressive, so that it is easy to
learn yet also provides all the features we need for the creation of web
documentation. The number of tags is kept to a minimum <d/> just those we need.
-This makes it easy to transform guide into other formats, such as DocBook
+This makes it easy to transform DevBook XML into other formats, such as DocBook
XML/SGML or web-ready HTML.
</p>
^ permalink raw reply related [flat|nested] 30+ messages in thread
* [gentoo-commits] proj/devmanual:master commit in: appendices/devbook-guide/
@ 2023-11-05 16:45 Ulrich Müller
0 siblings, 0 replies; 30+ messages in thread
From: Ulrich Müller @ 2023-11-05 16:45 UTC (permalink / raw
To: gentoo-commits
commit: 6a866ee284aa6f23d57ace74f9fca05a427de4fd
Author: Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Thu Nov 2 17:27:20 2023 +0000
Commit: Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Sun Nov 5 16:44:11 2023 +0000
URL: https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=6a866ee2
devbook-guide: Don't require blank lines in list items and table cells
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>
appendices/devbook-guide/text.xml | 2 ++
1 file changed, 2 insertions(+)
diff --git a/appendices/devbook-guide/text.xml b/appendices/devbook-guide/text.xml
index 7c12d6d..484a230 100644
--- a/appendices/devbook-guide/text.xml
+++ b/appendices/devbook-guide/text.xml
@@ -578,6 +578,8 @@ Both sections are described next.
<c><codesample></c>, <c><figure></c>, <c><table></c>,
<c><ul></c>, <c><ol></c>, <c><dl></c>, <c><note></c>,
<c><important></c> and <c><warning></c> (opening tags only).
+An exception to this rule applies to tags that are located within list items
+or table cells.
</p>
<p>
^ permalink raw reply related [flat|nested] 30+ messages in thread
* [gentoo-commits] proj/devmanual:master commit in: appendices/devbook-guide/
@ 2023-11-05 16:48 Ulrich Müller
0 siblings, 0 replies; 30+ messages in thread
From: Ulrich Müller @ 2023-11-05 16:48 UTC (permalink / raw
To: gentoo-commits
commit: ecc2c5953a5523ab3f4d9709066042c124bf40fc
Author: Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Sat Apr 16 07:16:43 2022 +0000
Commit: Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Sun Nov 5 16:47:49 2023 +0000
URL: https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=ecc2c595
devbook-guide: Document the todo element
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>
appendices/devbook-guide/text.xml | 29 ++++++++++++++++++++---------
1 file changed, 20 insertions(+), 9 deletions(-)
diff --git a/appendices/devbook-guide/text.xml b/appendices/devbook-guide/text.xml
index 484a230..5015f0b 100644
--- a/appendices/devbook-guide/text.xml
+++ b/appendices/devbook-guide/text.xml
@@ -178,6 +178,11 @@ This is important.
<warning>
This is a warning.
</warning>
+
+<todo>
+Text inside a <c>todo</c> element will appear in the
+<uri link="::appendices/todo-list/"/>.
+</todo>
</codesample>
<p>
@@ -212,6 +217,11 @@ This is important.
This is a warning.
</warning>
+<todo>
+Text inside a <c>todo</c> element will appear in the
+<uri link="::appendices/todo-list/"/>.
+</todo>
+
</body>
</subsection>
</section>
@@ -224,15 +234,16 @@ This is a warning.
We introduced a lot of new tags in the previous section <d/> here's what you
need to know. The <c><p></c> (paragraph), <c><pre></c>
(preformatted block), <c><codesample></c> (code block),
-<c><note></c>, <c><important></c> and <c><warning></c> tags
-all can contain one or more lines of text. Besides the <c><figure></c>,
-<c><table></c>, <c><ul></c>, <c><ol></c>
-and <c><dl></c> elements (which we'll cover in just a bit), these are the
-only tags that should appear immediately inside a <c><body></c> element.
-Another thing <d/> these tags <e>should not</e> be stacked <d/> 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> and <c><codesample></c> elements
-preserve their whitespace exactly, making them well-suited for code excerpts:
+<c><note></c>, <c><important></c>, <c><warning></c> and
+<c><todo></c> tags all can contain one or more lines of text.
+Besides the <c><figure></c>, <c><table></c>, <c><ul></c>,
+<c><ol></c> and <c><dl></c> elements (which we'll cover in just
+a bit), these are the only tags that should appear immediately inside a
+<c><body></c> element. Another thing <d/> these tags <e>should not</e>
+be stacked <d/> 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> and
+<c><codesample></c> elements preserve their whitespace exactly, making
+them well-suited for code excerpts:
</p>
<codesample lang="sgml"><!-- Named <pre> -->
^ permalink raw reply related [flat|nested] 30+ messages in thread
* [gentoo-commits] proj/devmanual:master commit in: appendices/devbook-guide/
@ 2024-05-08 5:57 Ulrich Müller
0 siblings, 0 replies; 30+ messages in thread
From: Ulrich Müller @ 2024-05-08 5:57 UTC (permalink / raw
To: gentoo-commits
commit: c09e7231f8c24cc0235abd494d8849a24138b76c
Author: Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Mon Apr 29 21:22:48 2024 +0000
Commit: Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Tue May 7 17:21:45 2024 +0000
URL: https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=c09e7231
devbook-guide: Document that sentence case should be used in titles
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>
appendices/devbook-guide/text.xml | 6 ++++++
1 file changed, 6 insertions(+)
diff --git a/appendices/devbook-guide/text.xml b/appendices/devbook-guide/text.xml
index 5c4aec7..c725307 100644
--- a/appendices/devbook-guide/text.xml
+++ b/appendices/devbook-guide/text.xml
@@ -696,6 +696,12 @@ with a capital letter.
</ul>
</codesample>
+<p>
+Titles should use sentence case, i.e. their first word should start with a
+capital letter, and all other words (except proper nouns) should be in lower
+case.
+</p>
+
<p>
Try to use <c><uri></c> with the <c>link</c> attribute as much as
possible. In other words, the
^ permalink raw reply related [flat|nested] 30+ messages in thread
* [gentoo-commits] proj/devmanual:master commit in: appendices/devbook-guide/
@ 2024-10-25 11:21 Ulrich Müller
0 siblings, 0 replies; 30+ messages in thread
From: Ulrich Müller @ 2024-10-25 11:21 UTC (permalink / raw
To: gentoo-commits
commit: ebce25b336d5e27ec1efa8193b11de38f1c4030d
Author: Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Thu Oct 24 17:57:22 2024 +0000
Commit: Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Thu Oct 24 17:57:22 2024 +0000
URL: https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=ebce25b3
devbook-guide: Clarify use of the term "tag"
- The XML declaration is not a tag.
- A tag cannot be closed; an element can (by a closing tag).
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>
appendices/devbook-guide/text.xml | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/appendices/devbook-guide/text.xml b/appendices/devbook-guide/text.xml
index c725307..b853b0b 100644
--- a/appendices/devbook-guide/text.xml
+++ b/appendices/devbook-guide/text.xml
@@ -40,7 +40,7 @@ used in a DevBook XML document:
</codesample>
<p>
-On the first lines, we see the requisite tag that identifies this as an XML
+On the first lines, we see the XML declaration that identifies this as an XML
document. Next, there's a <c><guide></c> tag <d/> the entire document is
enclosed within a <c><guide> </guide></c> pair. Its <c>self</c>
attribute must point to the relative path of the document from the root node;
@@ -55,7 +55,7 @@ document.
</p>
<p>
-All tags must be closed of course, so the document ends with:
+All elements must be closed of course, so the document ends with:
</p>
<codesample lang="sgml">
@@ -126,7 +126,7 @@ tag. Note that the trailing slash in the <c>href</c> value is mandatory.
<p>
A table of contents can be generated with <c><contentsTree></c>.
-Typically, this tag would be the only element in its own section body, as in
+Typically, this would be the only element in its own section body, as in
the following example:
</p>
^ permalink raw reply related [flat|nested] 30+ messages in thread
* [gentoo-commits] proj/devmanual:master commit in: appendices/devbook-guide/
@ 2024-10-31 18:59 Ulrich Müller
0 siblings, 0 replies; 30+ messages in thread
From: Ulrich Müller @ 2024-10-31 18:59 UTC (permalink / raw
To: gentoo-commits
commit: a9b79658d751269f442b4373d1cba36d00957a73
Author: Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Wed Oct 30 19:04:57 2024 +0000
Commit: Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Thu Oct 31 18:56:03 2024 +0000
URL: https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=a9b79658
devbook-guide: Restore commented-out captions of code samples
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>
appendices/devbook-guide/text.xml | 19 ++++++++++---------
1 file changed, 10 insertions(+), 9 deletions(-)
diff --git a/appendices/devbook-guide/text.xml b/appendices/devbook-guide/text.xml
index b853b0b..4fc23cc 100644
--- a/appendices/devbook-guide/text.xml
+++ b/appendices/devbook-guide/text.xml
@@ -32,7 +32,7 @@ Let's start learning the DevBook XML syntax. We'll start with the initial tags
used in a DevBook XML document:
</p>
-<codesample lang="sgml"><!-- The initial part of a DevBook XML document -->
+<codesample lang="sgml" caption="The preamble of a DevBook XML document">
<?xml version="1.0" encoding="UTF-8"?>
<guide self="appendices/devbook-guide/">
<chapter>
@@ -78,7 +78,7 @@ title. Here's an example section with a single subsection, consisting of a
paragraph:
</p>
-<codesample lang="sgml"><!-- Minimal DevBook example -->
+<codesample lang="sgml" caption="Minimal DevBook example">
<section>
<title>This is my section</title>
<subsection>
@@ -150,7 +150,7 @@ Now, it's time to learn how to mark up actual content. Here's the XML code for
an example <c><body></c> element:
</p>
-<codesample lang="sgml"><!-- Example of a body element -->
+<codesample lang="sgml" caption="Example of a body element">
<p>
This is a paragraph. <c>/etc/passwd</c> is a file.
<uri>https://www.gentoo.org/</uri> is my favorite website.
@@ -243,11 +243,12 @@ a bit), these are the only tags that should appear immediately inside a
be stacked <d/> 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> and
<c><codesample></c> elements preserve their whitespace exactly, making
-them well-suited for code excerpts:
+them well-suited for code excerpts. Both <c><pre></c> and
+<c><codesample></c> can have a <c>caption</c> attribute:
</p>
-<codesample lang="sgml"><!-- Named <pre> -->
-<pre>
+<codesample lang="sgml" caption="Named <pre>">
+<pre caption="Output of uptime">
# uptime
16:50:47 up 164 days, 2:06, 5 users, load average: 0.23, 0.20, 0.25
</pre>
@@ -627,7 +628,7 @@ the content.
An example for indentation is:
</p>
-<codesample lang="sgml"><!-- Indentation Example -->
+<codesample lang="sgml" caption="Indentation example">
<table>
<tr>
<th>Foo</th>
@@ -659,7 +660,7 @@ attribute. Break the line before the <c><uri></c> tag instead.
and the attribute value. As an example:
</p>
-<codesample lang="sgml"><!-- Attributes -->
+<codesample lang="sgml" caption="Attributes">
Wrong : <uri link = "https://www.gentoo.org/">
Correct: <uri link="https://www.gentoo.org/">
</codesample>
@@ -689,7 +690,7 @@ Every sentence, including those inside tables and listings, should start
with a capital letter.
</p>
-<codesample lang="sgml"><!-- Periods and capital letters -->
+<codesample lang="sgml" caption="Periods and capital letters">
<ul>
<li>No period</li>
<li>With period. Multiple sentences, remember?</li>
^ permalink raw reply related [flat|nested] 30+ messages in thread
end of thread, other threads:[~2024-10-31 18:59 UTC | newest]
Thread overview: 30+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2020-08-21 16:53 [gentoo-commits] proj/devmanual:master commit in: appendices/devbook-guide/ Ulrich Müller
-- strict thread matches above, loose matches on Subject: below --
2024-10-31 18:59 Ulrich Müller
2024-10-25 11:21 Ulrich Müller
2024-05-08 5:57 Ulrich Müller
2023-11-05 16:48 Ulrich Müller
2023-11-05 16:45 Ulrich Müller
2023-10-05 20:29 Ulrich Müller
2022-02-16 18:56 Ulrich Müller
2021-07-31 17:59 Ulrich Müller
2021-03-19 19:23 Ulrich Müller
2021-03-19 19:23 Ulrich Müller
2021-03-19 19:22 Ulrich Müller
2021-03-12 19:32 Ulrich Müller
2021-03-11 11:24 Ulrich Müller
2020-12-14 19:35 Ulrich Müller
2020-03-06 16:30 Ulrich Müller
2020-03-06 16:30 Ulrich Müller
2020-03-01 12:32 Ulrich Müller
2020-02-22 21:27 Ulrich Müller
2020-01-28 5:55 Ulrich Müller
2020-01-16 18:50 Ulrich Müller
2020-01-15 22:36 Ulrich Müller
2020-01-15 22:14 Ulrich Müller
2020-01-15 21:30 Ulrich Müller
2020-01-15 21:30 Ulrich Müller
2020-01-15 21:29 Ulrich Müller
2020-01-15 21:29 Ulrich Müller
2020-01-15 21:29 Ulrich Müller
2020-01-15 21:29 Ulrich Müller
2020-01-15 21:29 Ulrich Müller
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox