This is the mail archive of the docbook@lists.oasis-open.org mailing list for the DocBook project.

Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Announce: DocBook V4.2 Candidate Release 3 (fwd)

--- Begin Message --- 
The DocBook TC announces the third Candidate Release of DocBook V4.2.
Please give it a try and report the results of your efforts. If no
errors are reported in the next 30 days, the TC will be able to vote
to move it to Committee Specification status.

http://www.oasis-open.org/docbook/

The 4.2CR2 release was just totally botched by the brainless
maintainer.

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com>      | Before doing someone a favour,
http://www.oasis-open.org/docbook/ | make sure that he isn't a
Chair, DocBook Technical Committee | madman.--Eug\'ene Labiche
--- End Message ---
--- Begin Message --- 
Currently the enumerated systemitem classes include the following
network related info:

systemname
domainname
fqdomainname
groupname
ipaddress
username
etheraddress

I have encountered a frequent need for one more:

url

Note that this is not necessarily a clickable link like the ulink
element. Rather it is a literal URL printed in text, such as
"Sun's home page is at
<systemitem class="url">http://www.sun.com/</systemitem>."

I have also encountered a need to distinguish different kinds of
non-resolvable URLs, specifically:

XML namespace URIs
SAX feature names
SAX property names
JAXP feature names
SOAP Actions
RDDL purposes
RDDL natures

Doubtless there are others, and more are likely to be invented in the
future. For the moment, I've been using the
class attribute to separate these. However, I think the time has come
to add at least a url role to systemitem, or possibly skip that step
completely and go straight to a url element.

Questions:

1. Do we really need a uri element? or separate url, uri, urn elements?

2. Should this element have some sort of purpose or role attribute that
identifies the type of the URI? For example,

<uri class="url" role="namespace">http://www.w3.org/TR/2001/XInclude</uri>
<uri 
class="urn">urn:publicid:%2B:IDN+example.org:DTD+XML+Bookmarks+1.0:EN:XML</uri>

-- 
+-----------------------+------------------------+-------------------+
| Elliotte Rusty Harold | elharo@metalab.unc.edu | Writer/Programmer |
+-----------------------+------------------------+-------------------+ 
|           The XML Bible, 2nd Edition (IDG Books, 2001)             |
|             http://www.cafeconleche.org/books/bible2/              |
|   http://www.amazon.com/exec/obidos/ISBN=0764547607/cafeaulaitA/   |
+----------------------------------+---------------------------------+
|  Read Cafe au Lait for Java News:   http://www.cafeaulait.org/     | 
|  Read Cafe con Leche for XML News:  http://www.cafeconleche.org/   |
+----------------------------------+---------------------------------+
--- End Message ---
--- Begin Message --- 
/ Johannes Zellner <johannes@zellner.org> was heard to say:
| is there a reference or any other documentation for docbook slides?

By funny coincidence, I was working on that this weekend. And on
cleaning up the code. Expect a new, better documented release sometime
soon.

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com>      | When you can measure what you are
http://www.oasis-open.org/docbook/ | speaking about, and express it in
Chair, DocBook Technical Committee | numbers, you know something about
                                   | it; but when you cannot measure
                                   | it, when you cannot express it in
                                   | numbers, your knowledge is of a
                                   | meager and unsatisfactory kind: it
                                   | may be the beginning of knowledge,
                                   | but you have scarcely, in your
                                   | thoughts, advanced to the stage of
                                   | science.--William Thompson, Lord
                                   | Kelvin
--- End Message ---
--- Begin Message --- 
Hi,

is there a reference or any other documentation for docbook slides?

-- 
   Johannes
--- End Message ---
--- Begin Message --- 
book/ Peter Ring <pri@ddf.dk> was heard to say:
| The DTD itself is not changed frm CR1, does not contain the
| changes described in [2], and differs from what's tagged V42CR2
| in the CVS repository.

Oh, <expletive censored="yes"/>!

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com>      | One of the great misfortunes of
http://www.oasis-open.org/docbook/ | mankind is that even his good
Chair, DocBook Technical Committee | qualities are sometimes useless to
                                   | him, and that the art of employing
                                   | and well directing them is often
                                   | the latest fruit of his
                                   | experience.--Chamfort
--- End Message ---
--- Begin Message --- 
/ Adam Di Carlo <adam@onshore-devel.com> was heard to say:
| I found numerous references in docbook-xml 4.2 cr2 referring to itself
| as CR1.  Instances of the problem can be found easily with grep and
| are included below.

Yes, my bad. I had hoped to get away without a CR3 to fix this, but
now I'm thinking this is causing confusion.

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com>      | If someone tells you he is going
http://www.oasis-open.org/docbook/ | to make 'a realistic decision',
Chair, DocBook Technical Committee | you immediately understand that he
                                   | has resolved to do something
                                   | bad.--Mary McCarthy
--- End Message ---
--- Begin Message --- 
Here's an initial proposal for a new packagename element. As I recall, 
Norm prefers these to be posted here and to put them in SourceForge 
himself. If that's incorrect, just let me know where you'd like me to 
send this. Please note the open issues for discussion at the end.

Currently when referrring to Java package names such as
org.xml.sax or java.lang.reflect in DocBook documents it is
necessary to mark them up as literals because there is no more
specific construct which matches them. That is, they are not
classnames, vars, types, methodnames, exceptionnames, ooclasses,
oointerfaces, or any of the other constructs DocBook provides
for programming language markup.

I suggest adding a <packagename> to do this:

<para>
The <packagename>org.xml.sax</packagename> is the key
package in SAX.
</para>

This would also be useful in classsynopsis:

<classsynopsis language="Java">
  <packagename>org.xml.sax</packagename>
  <oointerface>
    <modifier>public</modifier>
    <interfacename>XMLReader</interfacename>
  </oointerface>
</classsynopsis>

I propose:

1.    Add a packagename element that has the same content
and attributes as classname:

<!ENTITY % packagename.module "INCLUDE">
<![%packagename.module;[
<!ENTITY % local.packagename.attrib "">
<!ENTITY % packagename.role.attrib "%role.attrib;">

<!ENTITY % packagename.element "INCLUDE">
<![%packagename.element;[
<!ELEMENT packagename (%smallcptr.char.mix;)*>
<!--end of packagename.element-->]]>

<!ENTITY % packagename.attlist "INCLUDE">
<![%classname.attlist;[
<!ATTLIST packagename
        %common.attrib;
        %packagename.role.attrib;
        %local.packagename.attrib;
 >
<!--end of packagename.attlist-->]]>
<!--end of packagename.module-->]]>


2.    Add packagename (or whatever it's called) to tech.char.class:

<!ENTITY % tech.char.class
        "action|application
                |classname|methodname|interfacename|exceptionname
                |ooclass|oointerface|ooexception
                |command|computeroutput
        |database|email|envar|errorcode|errorname|errortype|filename
        |function|guibutton|guiicon|guilabel|guimenu|guimenuitem
        |guisubmenu|hardware|interface|keycap
        |keycode|keycombo|keysym|literal|constant|markup|medialabel
        |menuchoice|mousebutton|option|optional|packagename|parameter
        |prompt|property|replaceable|returnvalue|sgmltag|structfield
        |structname|symbol|systemitem|token|type|userinput|varname
                %ebnf.inline.hook;
        %local.tech.char.class;"
 >
 

3. Add a single initial packagename as an optional child of classsynopsis:

<!ELEMENT classsynopsis (packagename?, (ooclass|oointerface|ooexception)+,
                         (classsynopsisinfo
                          |fieldsynopsis|%method.synop.class;)*)>

                         
Issues for discussion:

1. Is "packagename" the right name for symmetry with classname and
interfacename or should this be simply "package"? Or perhapps
"oopackage" for symmetry with ooclass and oointerface?

2. Is there any need for a package synopsis, either as its own element
 or a kind of classysnopsis?

3. I'm mostly familiar with Java. Is there anything similar in other
language we should address here; e.g. C++ or C# namespaces or Perl
modules? If so, how does this affect the choice of name for this element?
Also, do any of these languages ever put a single class or interface
in more than one package?

-- 
+-----------------------+------------------------+-------------------+
| Elliotte Rusty Harold | elharo@metalab.unc.edu | Writer/Programmer |
+-----------------------+------------------------+-------------------+ 
|           The XML Bible, 2nd Edition (IDG Books, 2001)             |
|             http://www.cafeconleche.org/books/bible2/              |
|   http://www.amazon.com/exec/obidos/ISBN=0764547607/cafeaulaitA/   |
+----------------------------------+---------------------------------+
|  Read Cafe au Lait for Java News:   http://www.cafeaulait.org/     | 
|  Read Cafe con Leche for XML News:  http://www.cafeconleche.org/   |
+----------------------------------+---------------------------------+
--- End Message ---
Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]