[gentoo-commits] proj/devmanual:master commit in: appendices/devbook-guide/
commit: c09e7231f8c24cc0235abd494d8849a24138b76c Author: Ulrich Müller gentoo org> AuthorDate: Mon Apr 29 21:22:48 2024 + Commit: Ulrich Müller gentoo org> CommitDate: Tue May 7 17:21:45 2024 + 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 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 + +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. + + Try to use uri with the link attribute as much as possible. In other words, the
[gentoo-commits] proj/devmanual:master commit in: appendices/devbook-guide/, /
commit: bd474970728035c6286f1071162efefd6f8d63e9
Author: Ulrich Müller gentoo org>
AuthorDate: Thu Feb 8 10:29:50 2024 +
Commit: Ulrich Müller gentoo org>
CommitDate: Thu Feb 8 10:29:50 2024 +
URL:https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=bd474970
devbook.xsl: Add sub and sup elements
These were present in GuideXML:
https://gitweb.gentoo.org/proj/devmanual.git/tree/appendices/contributing/devbook-guide/text.xml?id=8be0d382fb82dc4cfe73b1b85bb7fc3c923a21c7#n397
Signed-off-by: Ulrich Müller gentoo.org>
appendices/devbook-guide/text.xml | 7 ++-
devbook.rnc | 6 --
devbook.rng | 14 +-
devbook.xsl | 8
4 files changed, 31 insertions(+), 4 deletions(-)
diff --git a/appendices/devbook-guide/text.xml
b/appendices/devbook-guide/text.xml
index 5015f0b..8301b0a 100644
--- a/appendices/devbook-guide/text.xml
+++ b/appendices/devbook-guide/text.xml
@@ -465,7 +465,7 @@ together:
Inline elements
-c, b, and e
+c, b, e, sub and sup
@@ -495,6 +495,11 @@ offset from the regular paragraph type for emphasis. This
helps to give your
prose more punch!
+
+The sub and sup elements are used to specify
+subscript and superscript.
+
+
diff --git a/devbook.rnc b/devbook.rnc
index 158f372..22f7c09 100644
--- a/devbook.rnc
+++ b/devbook.rnc
@@ -1,4 +1,4 @@
-# Copyright 2022-2023 Gentoo Authors
+# Copyright 2022-2024 Gentoo Authors
# Distributed under the terms of the MIT license
# or the CC-BY-SA-4.0 license (dual-licensed)
@@ -7,7 +7,7 @@
block.class = p | pre | codesample | note | important | warning | todo
| figure | table | ul | ol | dl
-attrib.class = text | b | c | e
+attrib.class = text | b | c | e | sub | sup
inline.class = attrib.class | d | uri
attrib = attrib.class*
@@ -112,6 +112,8 @@ dd = element dd { all }
b = element b { inline }
c = element c { inline }
e = element e { inline }
+sub = element sub { inline }
+sup = element sup { inline }
d = element d { empty }
uri = element uri {
diff --git a/devbook.rng b/devbook.rng
index c3c616f..3963ab1 100644
--- a/devbook.rng
+++ b/devbook.rng
@@ -2,7 +2,7 @@
http://relaxng.org/ns/structure/1.0;
datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes;>
@@ -32,6 +32,8 @@
+
+
@@ -382,6 +384,16 @@
+
+
+
+
+
+
+
+
+
+
diff --git a/devbook.xsl b/devbook.xsl
index 71a74dd..6f2e4e9 100644
--- a/devbook.xsl
+++ b/devbook.xsl
@@ -280,6 +280,14 @@
+
+
+
+
+
+
+
+
abcdefghijklmnopqrstuvwxyz-
[gentoo-commits] proj/devmanual:master commit in: appendices/devbook-guide/
commit: ecc2c5953a5523ab3f4d9709066042c124bf40fc Author: Ulrich Müller gentoo org> AuthorDate: Sat Apr 16 07:16:43 2022 + Commit: Ulrich Müller gentoo org> CommitDate: Sun Nov 5 16:47:49 2023 + URL:https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=ecc2c595 devbook-guide: Document the todo element Signed-off-by: Ulrich Müller 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 ctodo/c element will appear in the +uri link="::appendices/todo-list/"/. +/todo @@ -212,6 +217,11 @@ This is important. This is a warning. + +Text inside a todo element will appear in the +. + + @@ -224,15 +234,16 @@ This is a warning. We introduced a lot of new tags in the previous section here's what you need to know. The p (paragraph), pre (preformatted block), codesample (code block), -note, important and warning tags -all can contain one or more lines of text. Besides the figure, -table, ul, ol -and dl elements (which we'll cover in just a bit), these are the -only tags that should appear immediately inside a body element. -Another thing these tags should not be stacked in other words, -don't put a note element inside a p element. As -you might guess, the pre and codesample elements -preserve their whitespace exactly, making them well-suited for code excerpts: +note, important, warning and +todo tags all can contain one or more lines of text. +Besides the figure, table, ul, +ol and dl elements (which we'll cover in just +a bit), these are the only tags that should appear immediately inside a +body element. Another thing these tags should not +be stacked in other words, don't put a note element inside +a p element. As you might guess, the pre and +codesample elements preserve their whitespace exactly, making +them well-suited for code excerpts:
[gentoo-commits] proj/devmanual:master commit in: appendices/devbook-guide/
commit: 6a866ee284aa6f23d57ace74f9fca05a427de4fd Author: Ulrich Müller gentoo org> AuthorDate: Thu Nov 2 17:27:20 2023 + Commit: Ulrich Müller gentoo org> CommitDate: Sun Nov 5 16:44:11 2023 + 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 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. codesample, figure, table, ul, ol, dl, note, important and warning (opening tags only). +An exception to this rule applies to tags that are located within list items +or table cells.
[gentoo-commits] proj/devmanual:master commit in: appendices/devbook-guide/
commit: acbf1e23650c3cad83ed0d39980032dcb885f7e7 Author: Ulrich Müller gentoo org> AuthorDate: Thu Oct 5 20:29:19 2023 + Commit: Ulrich Müller gentoo org> CommitDate: Thu Oct 5 20:29:19 2023 + URL:https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=acbf1e23 appendices/devbook-guide: GuideXML -> DevBook XML Signed-off-by: Ulrich Müller 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 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.
[gentoo-commits] proj/devmanual:master commit in: appendices/devbook-guide/
commit: ece9a5736c0a04daa7d03738a9b2624f088f85fa Author: Ulrich Müller gentoo org> AuthorDate: Wed Feb 16 18:54:40 2022 + Commit: Ulrich Müller gentoo org> CommitDate: Wed Feb 16 18:54:40 2022 + 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 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 align attribute. - -This title spans 4 columns - - -This title spans 6 rows -Item A1 -Item A2 -Item A3 - - -Item B1 -Blocky 2x2 title - - -Item C1 - - -Item D1..D3 - - -Item E1..F1 -Item E2..E3 - - -Item F2..F3 - + + This title spans 4 columns + + + This title spans 6 rows + Item A1 + Item A2 + Item A3 + + + Item B1 + Blocky 2x2 title + + + Item C1 + + + Item D1..D3 + + + Item E1..F1 + Item E2..E3 + + + Item F2..F3 +
[gentoo-commits] proj/devmanual:master commit in: appendices/devbook-guide/
commit: 2b798b92188375840ed1273bc1373ca1eb1f0f69 Author: Ulrich Müller gentoo org> AuthorDate: Sat Jul 31 08:23:35 2021 + Commit: Ulrich Müller gentoo org> CommitDate: Sat Jul 31 08:32:03 2021 + 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 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 title is used to set the title for the entire document. - -The title element cannot contain any newlines. Make sure it is -in one line, including its opening and closing tags. - - All tags must be closed of course, so the document ends with:
[gentoo-commits] proj/devmanual:master commit in: appendices/devbook-guide/
commit: 91b323cd575dff579191a767190e9d56ff255d44 Author: Ulrich Müller gentoo org> AuthorDate: Fri Mar 12 17:51:37 2021 + Commit: Ulrich Müller gentoo org> CommitDate: Fri Mar 19 19:19:39 2021 + 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 elements Code samples and colour-coding Figures Tables Lists Inline elements , , and Intra-document references Coding Style Internal Coding Style External Coding Style Signed-off-by: Ulrich Müller 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. -Devbook XML - Basic structure @@ -71,7 +69,7 @@ All tags must be closed of course, so the document ends with: - + Sections and subsections @@ -221,8 +219,10 @@ This is a warning. - -The body tags + + + +Body elements @@ -248,7 +248,7 @@ preserve their whitespace exactly, making them well-suited for code excerpts: - + Code samples and colour-coding @@ -454,6 +454,10 @@ together: + + + +Inline elements c, b, and e
[gentoo-commits] proj/devmanual:master commit in: appendices/devbook-guide/
commit: 621fa0991832f3eb80cf0ab26e55a2ba112fc53a
Author: Ulrich Müller gentoo org>
AuthorDate: Fri Mar 12 17:41:53 2021 +
Commit: Ulrich Müller gentoo org>
CommitDate: Fri Mar 19 19:19:39 2021 +
URL:https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=621fa099
devbook-guide: Move all inline elements together
Signed-off-by: Ulrich Müller 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
-
-
-
-c, b, and e
-
-
-
-The c element is used to mark up a command or user
-input. Think of 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
-element because they represent something that the user could type in that is
-not a path. By using c elements, you'll help your readers
-quickly identify commands that they need to type in. Also, because
-c elements are already offset from regular text, it is rarely
-necessary to surround user input with double-quotes. For example, don't
-refer to a "c" element like I did in this sentence. Avoiding
-the use of unnecessary double-quotes makes a document more readable and
-adorable!
-
-
-
-As you might have guessed, b is used to boldface some
-text.
-
-
-
-e is used to apply emphasis to a word or phrase; for example:
-I really 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 punch!
-
-
@@ -352,30 +319,6 @@ src_install() {
}
-
-
-
-uri
-
-
-
-The uri tag is used to point to files/locations on the Internet.
-It has two forms the first can be used when you want to have the actual
URI
-displayed in the body text, such as this link to
-https://www.gentoo.org/. To create this link, I typed
-urihttps://www.gentoo.org//uri;. The alternate form is
-when you want to associate a URI with some other text for example,
-https://www.gentoo.org/;>the Gentoo Linux website. To create
-this link, I typed uri link="https://www.gentoo.org/"the
-Gentoo Linux website/uri.
-
-
-
-Please avoid the https://en.wikipedia.org/wiki/Click_here;>click
here
-syndrome as recommended by the https://www.w3.org/QA/Tips/noClickHere;>W3C.
-
-
@@ -509,6 +452,63 @@ together:
The recipe may be improved by adding raisins.
+
+
+
+c, b, and e
+
+
+
+The c element is used to mark up a command or user
+input. Think of 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
+element because they represent something that the user could type in that is
+not a path. By using c elements, you'll help your readers
+quickly identify commands that they need to type in. Also, because
+c elements are already offset from regular text, it is rarely
+necessary to surround user input with double-quotes. For example, don't
+refer to a "c" element like I did in this sentence. Avoiding
+the use of unnecessary double-quotes makes a document more readable and
+adorable!
+
+
+
+As you might have guessed, b is used to boldface some
+text.
+
+
+
+e is used to apply emphasis to a word or phrase; for example:
+I really 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 punch!
+
+
+
+
+
+uri
+
+
+
+The uri tag is used to point to files/locations on the Internet.
+It has two forms the first can be used when you want to have the actual
+URI displayed in the body text, such as this link to
+https://www.gentoo.org/. To create this link, I typed
+urihttps://www.gentoo.org//uri;. The alternate form is
+when you want to associate a URI with some other text for example,
+https://www.gentoo.org/;>the Gentoo Linux website. To create
+this link, I typed uri link="https://www.gentoo.org/"the
+Gentoo Linux website/uri.
+
+
+
+Please avoid the https://en.wikipedia.org/wiki/Click_here;>click
+here syndrome as recommended by the
+https://www.w3.org/QA/Tips/noClickHere;>W3C.
+
+
[gentoo-commits] proj/devmanual:master commit in: appendices/devbook-guide/
commit: 7a84ee5d396486e897e3916022738b35de54ab6f Author: Ulrich Müller gentoo org> AuthorDate: Sun Mar 7 17:07:01 2021 + Commit: Ulrich Müller gentoo org> CommitDate: Fri Mar 19 19:19:08 2021 + 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 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 tr (from table), ul, ol and dl. If indentation is used, it must be two spaces for each indentation. That means no tabs and not more spaces. Besides, tabs are not allowed in -DevBook XML documents. +DevBook XML documents (again, except for pre and codesample).
[gentoo-commits] proj/devmanual:master commit in: appendices/devbook-guide/
commit: e554a3737446e302bfc7224c434c3719c554c950
Author: Sam James gentoo org>
AuthorDate: Fri Mar 12 18:23:49 2021 +
Commit: Ulrich Müller gentoo org>
CommitDate: Fri Mar 12 19:32:21 2021 +
URL:https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=e554a373
appendices/devbook-guide: fix formatting phase definition
Signed-off-by: Sam James gentoo.org>
Signed-off-by: Ulrich Müller 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
[gentoo-commits] proj/devmanual:master commit in: appendices/devbook-guide/
commit: 0099daa4739d635a7ab455450d531747b0f508d8 Author: Ulrich Müller gentoo org> AuthorDate: Thu Mar 11 11:24:03 2021 + Commit: Ulrich Müller gentoo org> CommitDate: Thu Mar 11 11:24:03 2021 + URL:https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=0099daa4 devbook-guide: Fix typo Signed-off-by: Ulrich Müller 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. Newlines must be placed immediately after every DevBook XML tag -(both opening as closing), except for: +(both opening and closing), except for: title, th, ti, li, dt, dd,
[gentoo-commits] proj/devmanual:master commit in: appendices/devbook-guide/, appendices/contributing/
commit: ba881fa1e70cf15082b6130080b9c799c8c491cc Author: Ulrich Müller gentoo org> AuthorDate: Mon Feb 15 07:48:30 2021 + Commit: Ulrich Müller gentoo org> CommitDate: Mon Feb 15 07:48:30 2021 + URL:https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=ba881fa1 devbook-guide: Note about dashes moved from contributing to here Signed-off-by: Ulrich Müller gentoo.org> appendices/contributing/text.xml | 5 - appendices/devbook-guide/text.xml | 7 +++ 2 files changed, 7 insertions(+), 5 deletions(-) diff --git a/appendices/contributing/text.xml b/appendices/contributing/text.xml index 1bc3b65..10ab565 100644 --- a/appendices/contributing/text.xml +++ b/appendices/contributing/text.xml @@ -135,11 +135,6 @@ amount of depth. This is not a formal document. The writing style is intended to be professional but readable. - - When using in-sentence hyphens as punctuation like this use a space, - followed by the d/ tag. The build system will automatically turn - this into a proper Unicode long dash. - diff --git a/appendices/devbook-guide/text.xml b/appendices/devbook-guide/text.xml index 70b4dab..d37bbce 100644 --- a/appendices/devbook-guide/text.xml +++ b/appendices/devbook-guide/text.xml @@ -647,6 +647,13 @@ Wrong : uri link = "https://www.gentoo.org/"; Correct: uri link="https://www.gentoo.org/"; + +Dashes used as in-sentence punctuation like this should be +written as a d/ tag surrounded by spaces. It would be difficult +to distinguish a Unicode em-dash from a hyphen when editing the source using a +fixed-width font. + +
[gentoo-commits] proj/devmanual:master commit in: appendices/devbook-guide/
commit: e9fa4f2fc58a9605a0f1b1e92dd01601452a5d92
Author: Ulrich Müller gentoo org>
AuthorDate: Mon Dec 14 19:26:53 2020 +
Commit: Ulrich Müller gentoo org>
CommitDate: Mon Dec 14 19:26:53 2020 +
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=markup
Signed-off-by: Ulrich Müller 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 body element:
p
This is a paragraph. c/etc/passwd/c is a file.
-urihttps://forums.gentoo.org//uri; is my favorite website.
+urihttps://www.gentoo.org//uri; is my favorite website.
Type cls/c if you feel like it. I ereally/e
want to go to sleep now.
/p
@@ -193,7 +193,7 @@ Now, here's how the body element above is
rendered:
This is a paragraph. /etc/passwd is a file.
-https://forums.gentoo.org/ is my favorite web site.
+https://www.gentoo.org/ is my favorite web site.
Type ls if you feel like it. I really want to go to sleep now.
@@ -362,12 +362,12 @@ src_install() {
The uri tag is used to point to files/locations on the Internet.
It has two forms the first can be used when you want to have the actual
URI
displayed in the body text, such as this link to
-https://forums.gentoo.org/. To create this link, I typed
-urihttps://forums.gentoo.org//uri;. The alternate form
is
+https://www.gentoo.org/. To create this link, I typed
+urihttps://www.gentoo.org//uri;. The alternate form is
when you want to associate a URI with some other text for example,
-https://forums.gentoo.org/;>the Gentoo Forums. To create
-this link, I typed uri link="https://forums.gentoo.org/"the
-Gentoo Forums/uri.
+https://www.gentoo.org/;>the Gentoo Linux website. To create
+this link, I typed uri link="https://www.gentoo.org/"the
+Gentoo Linux website/uri.
@@ -643,8 +643,8 @@ and the attribute value. As an example:
-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/";
@@ -674,8 +674,9 @@ with a capital letter.
Try to use uri with the link attribute as much as
-possible. In other words, the https://forums.gentoo.org/;>Gentoo
-Forums is preferred over https://forums.gentoo.org/.
+possible. In other words, the
+https://www.gentoo.org/;>Gentoo website is preferred over
+https://www.gentoo.org/.
[gentoo-commits] proj/devmanual:master commit in: appendices/devbook-guide/
commit: 786b3696c9b2f4bc57b28be30dda63c75a6fe59b Author: Ulrich Müller gentoo org> AuthorDate: Tue Aug 4 15:56:00 2020 + Commit: Ulrich Müller gentoo org> CommitDate: Fri Aug 21 16:49:24 2020 + 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 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 + +Opening tags with a single attribute may not be split between lines. +For example, don't put a newline between uri and its link +attribute. Break the line before the uri tag instead. + + Attributes may not have spaces in between the attribute, the "=" mark, and the attribute value. As an example:
[gentoo-commits] proj/devmanual:master commit in: appendices/devbook-guide/
commit: d7fd191af16b7ebe32ea13d5bef2c7ef1f0da538 Author: Ulrich Müller gentoo org> AuthorDate: Fri Mar 6 16:23:33 2020 + Commit: Ulrich Müller gentoo org> CommitDate: Fri Mar 6 16:23:33 2020 + 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 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. Definition lists (dl) are also supported. Please note that -neither the definition term tag (dt) nor the definition data tag -(dd) accept any other block level tag such as paragraphs or -admonitions. A definition list comprises: +the definition term tag (dt) does not accept any other block +level tag such as paragraphs or admonitions. A definition list comprises: dl A Definition List Tag containing dt - Definition Term Tags, + Definition Term Tags dd - each followed by one or more Definition Data Tags. + and Definition Data Tags. + + + +The following example copied from +https://www.w3.org/TR/REC-html40/struct/lists.html;>w3.org +shows that lists may also be nested and different list types may be used +together: + + + + The ingredients: + + + 100 g flour + 10 g sugar + 1 cup water + 2 eggs + salt, pepper + + + The procedure: + + + Mix dry ingredients thoroughly. + Pour in wet ingredients. + Mix for 10 minutes. + Bake for one hour at 300 degrees. + + + Notes: + The recipe may be improved by adding raisins.
[gentoo-commits] proj/devmanual:master commit in: appendices/devbook-guide/
commit: 92a1cf4b1f924f00d2a0eaa5d2e01f9bf404aad9 Author: Ulrich Müller gentoo org> AuthorDate: Fri Mar 6 16:24:37 2020 + Commit: Ulrich Müller gentoo org> CommitDate: Fri Mar 6 16:24:37 2020 + 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 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 here's what you need to know. The p (paragraph), pre (preformatted block), codesample (code block), -note, warning and important tags +note, important and warning tags all can contain one or more lines of text. Besides the figure, table, ul, ol and dl elements (which we'll cover in just a bit), these are the @@ -577,7 +577,7 @@ Both sections are described next. body (opening tag only) and before every section, p, pre, codesample, figure, table, -ul, ol, dl, note +ul, ol, dl, note, important and warning (opening tags only).
[gentoo-commits] proj/devmanual:master commit in: appendices/devbook-guide/
commit: 7b57dc9b70fec1d7c38c7a160e7f90b0e1063d89 Author: Ulrich Müller gentoo org> AuthorDate: Sun Mar 1 12:30:00 2020 + Commit: Ulrich Müller gentoo org> CommitDate: Sun Mar 1 12:30:00 2020 + URL:https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=7b57dc9b devbook-guide: Flip order of and examples. Signed-off-by: Ulrich Müller 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 @@ -211,14 +211,14 @@ Make HTML/XML easier to read by using selective emphasis: This is a note. - -This is a warning. - - This is important. + +This is a warning. + +
[gentoo-commits] proj/devmanual:master commit in: appendices/devbook-guide/
commit: 8bd0dfe59f40e09049e7fc86cb59da2aa51e1ee0 Author: Ulrich Müller gentoo org> AuthorDate: Sat Feb 22 21:25:47 2020 + Commit: Ulrich Müller gentoo org> CommitDate: Sat Feb 22 21:25:47 2020 + 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 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: uri link="::ebuild-writing/file-format/"/ and uri link="::quickstart/#First Ebuild"/ render as and -, respectively. +, respectively.
[gentoo-commits] proj/devmanual:master commit in: appendices/devbook-guide/
commit: e4018d0bb607ec164871ab536b2334507f46f069
Author: Ulrich Müller gentoo org>
AuthorDate: Tue Jan 28 05:54:30 2020 +
Commit: Ulrich Müller gentoo org>
CommitDate: Tue Jan 28 05:54:30 2020 +
URL:https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=e4018d0b
appendices/devbook-guide: Fix misplaced parentheses.
Signed-off-by: Ulrich Müller 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 body
element in a bit.
The chapter, section, subsection
-and subsubsection) elements contain a body and/or
+and subsubsection elements contain a body 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.
@@ -619,7 +619,7 @@ Correct: uri link="https://forums.gentoo.org/";
Inside tables (table) and listings (ul,
-ol) and dl, periods (".") should not be used
+ol and dl), periods (".") should not be used
unless multiple sentences are used. In that case, every sentence should end
with a period (or other reading marks).
[gentoo-commits] proj/devmanual:master commit in: appendices/devbook-guide/
commit: 81df8e36aeecf7234cd669ae593d1b5731cc01c5 Author: Ulrich Müller gentoo org> AuthorDate: Thu Jan 16 18:44:20 2020 + Commit: Ulrich Müller gentoo org> CommitDate: Thu Jan 16 18:44:20 2020 + 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 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 @@ Gentoo DevBook XML Guide -DevBook XML basics - DevBook XML design goals @@ -23,7 +21,6 @@ documents. - @@ -515,8 +512,6 @@ I could have written the two examples above in more compact form: Coding Style - -Introduction @@ -532,7 +527,7 @@ Both sections are described next. - + Internal Coding Style
[gentoo-commits] proj/devmanual:master commit in: appendices/devbook-guide/
commit: 75a0de8654435df5ca5b12b2670e24258d30ffc9 Author: Ulrich Müller gentoo org> AuthorDate: Wed Jan 15 22:35:17 2020 + Commit: Ulrich Müller gentoo org> CommitDate: Wed Jan 15 22:35:17 2020 + URL:https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=75a0de86 devbook-guide: Remove obsolete text in "" 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 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 body element: p This is a paragraph. c/etc/passwd/c is a file. -urihttps://forums.gentoo.org/uri; is my favorite website. +urihttps://forums.gentoo.org//uri; is my favorite website. Type cls/c if you feel like it. I ereally/e want to go to sleep now. /p @@ -196,7 +196,7 @@ Now, here's how the body element above is rendered: This is a paragraph. /etc/passwd is a file. -https://forums.gentoo.org is my favorite web site. +https://forums.gentoo.org/ is my favorite web site. Type ls if you feel like it. I really want to go to sleep now. @@ -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 for example, https://forums.gentoo.org/;>the Gentoo Forums. To create this link, I typed uri link="https://forums.gentoo.org/"the -Gentoo Forums/uri. You don't need to write -https://www.gentoo.org/ to link to other parts of the Gentoo web site. -For instance, a link to the documentation main index -should be simply uri link="/doc/en/index.xml"documentation main -index/uri. You can even omit index.xml when you link to a -directory index, e.g. uri link="/doc/en/"documentation main -index/uri. Leaving the trailing slash saves an extra HTTP request. +Gentoo Forums/uri. @@ -649,8 +643,8 @@ with a capital letter. Try to use uri with the link attribute as much as -possible. In other words, the https://forums.gentoo.org;>Gentoo -Forums is preferred over https://forums.gentoo.org. +possible. In other words, the https://forums.gentoo.org/;>Gentoo +Forums is preferred over https://forums.gentoo.org/.
[gentoo-commits] proj/devmanual:master commit in: appendices/devbook-guide/
commit: 2cd4880c0d7f41313678e69367cdcb703b90c74e Author: Ulrich Müller gentoo org> AuthorDate: Wed Jan 15 22:14:04 2020 + Commit: Ulrich Müller gentoo org> CommitDate: Wed Jan 15 22:14:04 2020 + URL:https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=2cd4880c devbook-guide: Typo. Signed-off-by: Ulrich Müller 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. Blank lines must be placed immediately after every body (opening tag only) and before every section, p, pre, -codesample, figure;, table, +codesample, figure, table, ul, ol, dl, note important and warning (opening tags only).
[gentoo-commits] proj/devmanual:master commit in: appendices/devbook-guide/
commit: 3a84fac87dd431fbfbdddf51dcf34e6bcc71b6c6 Author: Ulrich Müller gentoo org> AuthorDate: Sat Jan 11 20:05:40 2020 + Commit: Ulrich Müller gentoo org> CommitDate: Wed Jan 15 21:28:46 2020 + URL:https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=3a84fac8 devbook-guide: Section on including sub-documents. Signed-off-by: Ulrich Müller 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. + + + +Including sub-documents + + + +The manual is organized as a tree. Each directory contains one document, which +can include multiple sub-documents using the include href="foo/"/ +tag. Note that the trailing slash in the href value is mandatory. + + + +A table of contents can be generated with contentsTree. +Typically, this tag would be the only element in its own section body, as in +the following example: + + + +section +titleContents/title +body +contentsTree/ +/body +/section + +
[gentoo-commits] proj/devmanual:master commit in: appendices/devbook-guide/
commit: d10a853abe03569b235f960693f47960c494fd9b
Author: Ulrich Müller gentoo org>
AuthorDate: Sat Jan 11 10:10:07 2020 +
Commit: Ulrich Müller gentoo org>
CommitDate: Wed Jan 15 21:28:45 2020 +
URL:https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=d10a853a
devbook-guide: Explain .
Signed-off-by: Ulrich Müller 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 punch!
Code samples and colour-coding
-
-Fill this section with the information about the use of
-codesample/.
-
+
+The pre tag does not support any syntax highlighting. When you
+need syntax highlighting, use the codesample tag along with a
+lang attribute usually you want this to be set to "ebuild"
+to syntax highlight ebuild code snippets. Currently, the following languages
+are supported:
+
+
+
+ c
+ ebuild
+ make
+ m4
+ sgml
+
+
+
+Remember that all leading and trailing spaces, and line breaks in
+codesample blocks will appear in the displayed html page.
+
+
+
+Sample codesample lang="c" block:
+
+
+
+#include stdio.h
+
+main()
+{
+ /* This is a comment */
+ printf("Hello, world!\n");
+}
+
+
+
+You can also specify numbering="lines" to enable line numbering, as in
+the following example:
+
+
+
+# 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
+}
+
[gentoo-commits] proj/devmanual:master commit in: appendices/devbook-guide/
commit: a8c06515b2da4df8a858e21c72ce446dd6abd998 Author: Ulrich Müller gentoo org> AuthorDate: Sat Jan 11 08:33:46 2020 + Commit: Ulrich Müller gentoo org> CommitDate: Wed Jan 15 21:28:44 2020 + 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 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: ?xml version="1.0" encoding="UTF-8"? -!DOCTYPE guide SYSTEM "/dtd/guide.dtd" -!-- Header -- - -guide lang="en" -titleGentoo Documentation Guide/title - -author title="Author" - mail link="yourn...@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"/ - -version1/version -date2011-11-29/date +guide self="appendices/devbook-guide/" +chapter +titleGentoo GuideXML Guide/title On the first lines, we see the requisite tag that identifies this as an XML -document and specifies its DTD. The !-- Header -- line -will be automatically modified by the CVS server and helps to track revisions. -Next, there's a guide tag the entire guide document is -enclosed within a guide /guide pair. - - - -The lang attribute should be used to specify the language code of your -document. It is used to format the date and insert strings like "Note", -"Content", etc. in the specified language. The default is English. - - - -Next, there's a title tag, used to set the title for the entire -guide document. +document. Next, there's a guide tag the entire document is +enclosed within a guide /guide pair. Its self +attribute must point to the relative path of the document from the root node; +in the example above the path is appendices/devbook-guide/. An exception +is the root node itself, which has guide root="true" instead. -Then, we come to the author tags, which contain information -about the various authors of the document. Each author tag -allows for an optional title 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 a -mail tag, used to specify an email address for this particular -person. The mail tag is optional and can be omitted, and at -least one author element is required per guide document. +Next, there is a chapter tag. Every document must have exactly +one chapter. Its title is used to set the title for the entire +document. - -Next, we come to the abstract, version and -date tags, used to specify a summary of the document, the -current version number, and the current version date (in -MM-DD format) -respectively. Dates that are invalid or not in the -MM-DD format will -appear verbatim in the rendered document. - + +The title element cannot contain any newlines. Make sure it is +in one line, including its opening and closing tags. + -This sums up the tags that should appear at the beginning of a guide document. -Besides the title and mail tags, these tags -shouldn't appear anywhere else except immediately inside the -guide 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: - -Finally we have the license version="3.0"/ tag, used to publish -the document under the https://creativecommons.org/licenses/by-sa/3.0/;>Creative -Commons - Attribution / Share Alike license as required by the Documentation Policy. Historically, -the tag license / was used, which denoted the 2.5 version of the -license. This is still accepted/allowed. - + +/chapter +/guide + -Chapters and sections +Sections and subsections 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 previous excerpt and append a -/guide 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
[gentoo-commits] proj/devmanual:master commit in: appendices/devbook-guide/
commit: eda9eff6a5393887b56679df3ff9c4107e1e4674 Author: Ulrich Müller gentoo org> AuthorDate: Sat Jan 11 19:44:54 2020 + Commit: Ulrich Müller gentoo org> CommitDate: Wed Jan 15 21:28:46 2020 + 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 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: GuideXML makes it really easy to reference other parts of the document using -hyperlinks. You can create a link pointing to Chapter -One by typing uri link="#doc_chap1"Chapter -One/uri. To point to section two of -Chapter One, type uri link="#doc_chap1_sect2"section two of -Chapter One/uri. To refer to figure 3 in chapter 1, type -uri link="#doc_chap1_fig3"figure 1.3/uri. Or, to refer -to code listing 2 in chapter 2, type -uri link="#doc_chap2_pre2"code listing 2.2/uri. +hyperlinks. You can create a link pointing to another chapter, like +Ebuild File Format, by typing +uri link="::ebuild-writing/file-format/"Ebuild File +Format/uri, i.e., two colons followed by the relative path from +the root node. To refer to a section in another chapter, like +First Ebuild, type +uri link="::quickstart/#First Ebuild"First Ebuild/uri. + + + +If the link target's chapter (or section etc.) title is to be used as the link +text, an empty uri element can be used. As a matter of fact, +I could have written the two examples above in more compact form: +uri link="::ebuild-writing/file-format/"/ and +uri link="::quickstart/#First Ebuild"/ render as + and +, respectively.
[gentoo-commits] proj/devmanual:master commit in: appendices/devbook-guide/
commit: 710b619980ed23811cbc0841466b9502a2c92278 Author: Ulrich Müller gentoo org> AuthorDate: Wed Jan 15 21:09:28 2020 + Commit: Ulrich Müller gentoo org> CommitDate: Wed Jan 15 21:28:47 2020 + 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 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 @@ -Gentoo GuideXML Guide +Gentoo DevBook XML Guide -GuideXML basics +DevBook XML basics -GuideXML design goals +DevBook XML design goals -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 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. -The goal is to make it easy to create and transform guideXML +The goal is to make it easy to create and transform DevBook XML documents. @@ -27,21 +27,21 @@ documents. -GuideXML +Devbook XML Basic structure -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: - + ?xml version="1.0" encoding="UTF-8"? guide self="appendices/devbook-guide/" chapter -titleGentoo GuideXML Guide/title +titleGentoo DevBook XML Guide/title @@ -88,7 +88,7 @@ title. Here's an example section with a single subsection, consisting of a paragraph: - + section titleThis is my section/title subsection @@ -408,8 +408,8 @@ for adding images without captions, borders, etc. -GuideXML supports a simplified table syntax similar to that of HTML. To start a -table, use a table tag. Start a row with a tr +DevBook XML supports a simplified table syntax similar to that of HTML. To start +a table, use a table tag. Start a row with a tr tag. However, for inserting actual table data, we don't support the HTML td tag; instead, use the th if you are inserting a header, and ti if you are inserting a normal informational @@ -495,7 +495,7 @@ admonitions. A definition list comprises: -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 Ebuild File Format, by typing uri link="::ebuild-writing/file-format/"Ebuild File @@ -544,8 +544,8 @@ Both sections are described next. -Newlines must be placed immediately after every -GuideXML-tag (both opening as closing), except for: +Newlines must be placed immediately after every DevBook XML tag +(both opening as closing), except for: version, date, title, th, ti, li, i, e, @@ -577,7 +577,7 @@ parent XML-tags are tr (from table), ul, ol and dl. If indentation is used, it must be two spaces for each indentation. That means no tabs and not more spaces. Besides, tabs are not allowed in -GuideXML documents. +DevBook XML documents.
[gentoo-commits] proj/devmanual:master commit in: appendices/devbook-guide/
commit: 46fe68d000cd1dfd48ddbb829ce8a3a1ad24e19f Author: Ulrich Müller gentoo org> AuthorDate: Sat Jan 11 09:03:49 2020 + Commit: Ulrich Müller gentoo org> CommitDate: Wed Jan 15 21:28:44 2020 + URL:https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=46fe68d0 devbook-guide: Make codesamples agree with their rendering. Mention and as subelements of . Signed-off-by: Ulrich Müller 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 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. urihttps://forums.gentoo.org/uri; is my favorite website. -Type cls/c if you feel like it. I ereally/e want to go to sleep now. +Type cls/c if you feel like it. I ereally/e want to go to sleep now. /p pre This is text output or code. -# ithis is user input/i +# this is user input +/pre +codesample lang="sgml" Make HTML/XML easier to read by using selective emphasis: -fooibar/i/foo -/pre +lt;foogt;barlt;/foogt; +/codesample note This is a note. @@ -166,15 +168,17 @@ Now, here's how the body element above is rendered: -This is a paragraph. /etc/passwd is a file. +This is a paragraph. /etc/passwd is a file. https://forums.gentoo.org is my favorite web site. -Type ls if you feel like it. I really want to go to sleep now. +Type ls if you feel like it. I really want to go to sleep now. - + This is text output or code. # this is user input + + Make HTML/XML easier to read by using selective emphasis: foobar/foo @@ -199,21 +203,22 @@ This is important. We introduced a lot of new tags in the previous section here's what you -need to know. The p (paragraph), pre (code block), -note, warning (warning) and -important (important) tags all can contain one or more lines of -text. Besides the table, ul, ol +need to know. The p (paragraph), pre +(preformatted block), codesample (code block), +note, warning and important tags +all can contain one or more lines of text. Besides the figure, +table, ul, ol and dl elements (which we'll cover in just a bit), these are the only tags that should appear immediately inside a body element. Another thing these tags should not be stacked in other words, don't put a note element inside a p element. As -you might guess, the pre element preserves its whitespace -exactly, making it well-suited for code excerpts: +you might guess, the pre and codesample elements +preserve their whitespace exactly, making them well-suited for code excerpts: pre -# iuptime/i +# uptime 16:50:47 up 164 days, 2:06, 5 users, load average: 0.23, 0.20, 0.25 /pre
[gentoo-commits] proj/devmanual:master commit in: appendices/devbook-guide/
commit: e01f0401b79a3de5a0bb29e98918ee72cef249c7 Author: Ulrich Müller gentoo org> AuthorDate: Wed Jan 15 21:25:12 2020 + Commit: Ulrich Müller gentoo org> CommitDate: Wed Jan 15 21:28:48 2020 + 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 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. Newlines must be placed immediately after every DevBook XML tag (both opening as closing), except for: -version, date, title, -th, ti, -li, i, e, -uri, path, b, c, -mail. +title, +th, ti, li, +dt, dd, +b, c, e, d/, +uri. @@ -564,11 +564,12 @@ Both sections are described next. Word-wrapping must be applied at 80 characters except inside -pre. 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 rendered content of pre elements within 80 -columns to help console users. +pre and codesample. 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 rendered content of +pre and codesample elements within 80 columns +to help console users.
