docs/56729: [patch] artciles/pr-guidelines: explain meaning of MFC
Ceri Davies
ceri at FreeBSD.org
Wed Sep 17 22:09:29 UTC 2003
On Fri, Sep 12, 2003 at 04:11:26PM +0200, Josef El-Rayes wrote:
> Ceri Davies <setantae at submonkey.net> wrote:
> > Yeah, those are the lines I was thinking along.
> > My reference to "relevant elements" was that there are very likely <glossary>
> > elements or similar already, which we can make use of.
>
> i wanted to start collecting some terms for glossary as some questions
> arose:
>
> i am wondering on how to realize this. should it be more of an index,
> with a crosslink to the place where it gets explained or like this:
>
> MFC: ...merge from current, action... <a href="..">read handbook..</a>
>
> with a short explanation and a link when there is a place where it gets
> explainend more detailed.
>
> should there be a certain "treshhold" like, only use freebsd specific
> terms or not trivial terms or should we include every term like "unix,
> ports, packages..."?
See the attached patch.
I have started out with only including FreeBSD specific terms in the
freebsd-glossary.sgml. There's no reason why we couldn't then have another
file containing generic computing terms (but personally, I'm not sure that
is necessary), although the build would need to be tweaked a bit.
I've also included a change to the handbook build that will allow you to
build in the glossary by running "make GLOSSARY=yes", but which is off by
default.
Note that there are not many entries at the moment; once this is committed
then people can feel free to add stuff to it - I've chosen the current entries
to illustrate the docbook way of GlossSeeAlso, GlossSee, etc, elements.
Any thoughts?
Ceri
PS. I can see a problem already with the link to the FAQ not working when
built with an article, but I'm not sure of the best way to fix it.
--
User: DO YOU ACCEPT JESUS CHRIST AS YOUR PERSONAL LORD AND SAVIOR?
Iniaes: Sure, I can accept all forms of payment.
-- www.chatterboxchallenge.com
-------------- next part --------------
Index: doc/en_US.ISO8859-1/books/handbook/Makefile
===================================================================
RCS file: /home/dcvs/doc/en_US.ISO8859-1/books/handbook/Makefile,v
retrieving revision 1.66
diff -u -r1.66 Makefile
--- doc/en_US.ISO8859-1/books/handbook/Makefile 15 Aug 2003 12:28:17 -0000 1.66
+++ doc/en_US.ISO8859-1/books/handbook/Makefile 17 Sep 2003 21:28:01 -0000
@@ -31,6 +31,7 @@
FORMATS?= html-split
HAS_INDEX= true
+GLOSSARY?=
INSTALL_COMPRESSED?= gz
INSTALL_ONLY_COMPRESSED?=
@@ -172,6 +173,9 @@
CHAPTERS?= ${SRCS:M*chapter.sgml}
SGMLFLAGS+= ${CHAPTERS:S/\/chapter.sgml//:S/^/-i chap./}
+.if defined(GLOSSARY) && !empty(GLOSSARY)
+SGMLFLAGS+= -i chap.freebsd-glossary
+.endif
# XXX The Handbook build currently overflows some internal, hardcoded
# limits in pdftex. Until we split the Handbook up, build the PDF
Index: doc/en_US.ISO8859-1/books/handbook/book.sgml
===================================================================
RCS file: /home/dcvs/doc/en_US.ISO8859-1/books/handbook/book.sgml,v
retrieving revision 1.141
diff -u -r1.141 book.sgml
--- doc/en_US.ISO8859-1/books/handbook/book.sgml 5 Sep 2003 21:30:20 -0000 1.141
+++ doc/en_US.ISO8859-1/books/handbook/book.sgml 17 Sep 2003 21:28:01 -0000
@@ -54,6 +54,7 @@
<!ENTITY % chap.eresources "IGNORE">
<!ENTITY % chap.pgpkeys "IGNORE">
<!ENTITY % chap.index "IGNORE">
+<!ENTITY % chap.freebsd-glossary "IGNORE">
<!ENTITY % pgpkeys SYSTEM "../../../share/pgpkeys/pgpkeys.ent"> %pgpkeys;
]>
@@ -236,6 +237,7 @@
<![ %chap.pgpkeys; [ &chap.pgpkeys; ]]>
<![ %chap.index; [ &chap.index; ]]>
</part>
+ <![ %chap.freebsd-glossary; [ &bookinfo.freebsd-glossary; ]]>
&chap.colophon;
</book>
Index: doc/en_US.ISO8859-1/share/sgml/bookinfo.ent
===================================================================
RCS file: /home/dcvs/doc/en_US.ISO8859-1/share/sgml/bookinfo.ent,v
retrieving revision 1.3
diff -u -r1.3 bookinfo.ent
--- doc/en_US.ISO8859-1/share/sgml/bookinfo.ent 17 Jun 2003 19:32:40 -0000 1.3
+++ doc/en_US.ISO8859-1/share/sgml/bookinfo.ent 17 Sep 2003 21:28:01 -0000
@@ -12,3 +12,5 @@
<!ENTITY bookinfo.legalnotice SYSTEM "legalnotice.sgml">
<!ENTITY bookinfo.trademarks SYSTEM "trademarks.sgml">
+
+<!ENTITY bookinfo.freebsd-glossary SYSTEM "glossary/freebsd-glossary.sgml">
Index: doc/en_US.ISO8859-1/share/sgml/glossary/freebsd-glossary.sgml
===================================================================
RCS file: doc/en_US.ISO8859-1/share/sgml/glossary/freebsd-glossary.sgml
diff -N doc/en_US.ISO8859-1/share/sgml/glossary/freebsd-glossary.sgml
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ doc/en_US.ISO8859-1/share/sgml/glossary/freebsd-glossary.sgml 17 Sep 2003 21:28:01 -0000
@@ -0,0 +1,64 @@
+<!--
+ FreeBSD Specific Glossary Terms
+ Please keep this file sorted.
+
+ $FreeBSD$
+-->
+
+<glossary status="draft" id="freebsd-glossary">
+ <title>&os; Glossary</title>
+ <para>This glossary contains terms and acronyms specific to &os;.</para>
+
+ <glossdiv>
+ <title>B</title>
+
+ <glossentry id="bikeshed">
+ <glossterm>Bikeshed Building</glossterm>
+ <glossdef>
+ <para>A phenomenon whereby many people will give an opinion on
+ an uncomplicated topic, whilst a complex topic receives little
+ or no discussion. See the
+ <ulink url="../faq/misc.html#BIKESHED-PAINTING">FAQ</ulink> for
+ the origin of the term.</para>
+ </glossdef>
+ </glossentry>
+ </glossdiv>
+
+ <glossdiv>
+ <title>M</title>
+
+ <glossentry id="mfc">
+ <glossterm>Merge From Current</glossterm>
+ <acronym>MFC</acronym>
+ <glossdef>
+ <para>To merge functionality or a patch from the -CURRENT
+ branch to another, most often -STABLE.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="mfs">
+ <glossterm>Merge From Stable</glossterm>
+ <acronym>MFS</acronym>
+ <glossdef>
+ <para>In the normal course of FreeBSD development, a change will
+ be committed to the -CURRENT branch for testing before being
+ merged to -STABLE. On rare occassions, a change will go into
+ -STABLE first and then be merged to -CURRENT.</para>
+ <glossseealso otherterm="mfc">
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>MFC</glossterm>
+ <glosssee otherterm="mfc">
+ </glossentry>
+
+ <glossentry>
+ <glossterm>MFS</glossterm>
+ <glosssee otherterm="mfs">
+ </glossentry>
+
+ </glossdiv>
+
+</glossary>
+
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 187 bytes
Desc: not available
URL: <http://lists.freebsd.org/pipermail/freebsd-doc/attachments/20030917/7f973a3d/attachment.sig>
More information about the freebsd-doc
mailing list