OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

Mail Index message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: docbook-digest Digest #197

Re: DOCBOOK: Re: marking up keycaps according to their semantics
Re: DOCBOOK: Re: Working with XInclude / xml:base / libxml v2.4.24 and
 above
Re: DOCBOOK: Re: marking up keycaps according to their semantics
DOCBOOK: website 'ideological' problems
DOCBOOK: Markup for UNIX signals
DOCBOOK: Re: Working with XInclude / xml:base / libxml v2.4.24 and
 above
Re: DOCBOOK: Re: documenting an API: RFE
DOCBOOK: Re: marking up keycaps according to their semantics
DOCBOOK: Re: website 'ideological' problems
DOCBOOK: Re: Markup for UNIX signals
Re: DOCBOOK: Re: marking up keycaps according to their semantics
Re: DOCBOOK: Re: marking up keycaps according to their semantics
Re: DOCBOOK: Re: marking up keycaps according to their semantics
RE: DOCBOOK: Re: Markup for UNIX signals
Re: DOCBOOK: Re: marking up keycaps according to their semantics
Re: DOCBOOK: Re: marking up keycaps according to their semantics
RE: DOCBOOK: Re: any reason why a "procedure" is not a child of "para"?
RE: DOCBOOK: Re: any reason why a "procedure" is not a child of "para"?
Re: DOCBOOK: Re: marking up keycaps according to their semantics
Re: DOCBOOK: Re: marking up keycaps according to their semantics
Re: DOCBOOK: Re: any reason why a "procedure" is not a child of "para"?
Re: DOCBOOK: Re: any reason why a "procedure" is not a child of "para"?
RE: DOCBOOK: Re: any reason why a "procedure" is not a child of "para"?

----------------------------------------------------------------
To subscribe or unsubscribe from this elist use the subscription
manager: <http://lists.oasis-open.org/ob/adm.pl>


Norman Walsh wrote:


> That is the question. At first I thought you were proposing only
> Control, Shift, Meta, and Alt.


not enough IMHO

> Though I suppose Command and Apple need
> to be in there as well.


yep, since they are widely used

> I've forgotten what the meta keys were on a
> 3270 and a VT100/220. Not to mention the Tectronix displays that I
> heard of but never used.


Nothing can ever cover every function key that ever existed or could 
exist (just as DocBook doesn't cover every possible documentation 
markup). If you can't remember what the meta keys were on a 3270 and a 
VT100/220, then I don't see much reason to include them. But they could 
still be included; IMHO it's not a big problem if the enumerated list 
for the attribute is 20 instead of 10 values, or 30 instead of 20.


> We need to really nail these down.


Yep; thanks for your help :)

> What's missing from this list:
> 
> control, shift, meta, alt,


those are in the list already

> command, apple, fn,
> esc, f1..f24, printscreen, sysreq, pause, break, windows, menu,
> backspace, home, pgup, pgdn, end, tab, backtab, capslock,


feel free to add those to the list on the RFE page


> up, down, left, right,


those are already in there as well

> ins, del


... and as I think I said, the list is just a first draft (I wrote 
"starting point"); it is not yet complete (where complete means all the 
stuff which is widely used).


> And how does this proposal deal with double-shifted keys? What's the right
> markup in this proposal for "Ctrl-Alt-Backspace" and "Alt-Shift-I"?


My requirement, as I said, is to be able to markup input comands as 
such, without relying on arbitrary ASCII renderings which are not 
standardized in the DocBook spec. The exact syntax is not relevant for 
me. But your question could probably be answered as:

<keycombo action="simul">
   <keycap function="control"/>
   <keycap function="alt"/>
   <keycap function="backspace"/>
</keycombo>

<keycombo action="simul">
   <keycap function="alt"/>
   <keycap function="shift"/>
   <keycap>I</keycap>
</keycombo>


Tobi


-- 
http://www.pinkjuice.com/




At 7:51 AM -0500 3/12/03, Norman Walsh wrote:

>No. The base URI in both cases is: http://www.example.com/docs/
>
>The base URI is not the same as the "document URI".

I agree that would be nicer, and it makes more sense; but it's not my 
reading of either the XML Infoset or the XML Base specification. In 
particular, section 4.1 of the XML Base spec 
<http://www.w3.org/TR/xmlbase/#rfc2396> states,

RFC 2396 [IETF RFC 2396] provides for base URI information to be 
embedded within a document. The rules for determining the base URI 
can be summarized as follows (highest priority to lowest):

    1. The base URI is embedded in the document's content.
    2. The base URI is that of the encapsulating entity (message, 
document, or none).
    3. The base URI is the URI used to retrieve the entity.
    4. The base URI is defined by the context of the application.

Assuminng there's no xml:base attribute in scope, then either 2 or 3 
applies. Both use the base URI of the document itself, not the 
directory where the document is found.  RFC 2396 seems to say the 
same thing. What am I missing?
-- 

+-----------------------+------------------------+-------------------+
| Elliotte Rusty Harold | elharo@metalab.unc.edu | Writer/Programmer |
+-----------------------+------------------------+-------------------+
|           Processing XML with Java (Addison-Wesley, 2002)          |
|              http://www.cafeconleche.org/books/xmljava             |
| http://www.amazon.com/exec/obidos/ISBN%3D0201771861/cafeaulaitA  |
+----------------------------------+---------------------------------+
|  Read Cafe au Lait for Java News:  http://www.cafeaulait.org/      |
|  Read Cafe con Leche for XML News: http://www.cafeconleche.org/    |
+----------------------------------+---------------------------------+



On Wed, 12 Mar 2003, Tobias Reif wrote:

> <keycombo action="simul">
>    <keycap function="control"/>
>    <keycap function="alt"/>
>    <keycap function="backspace"/>
> </keycombo>
> 
> <keycombo action="simul">
>    <keycap function="alt"/>
>    <keycap function="shift"/>
>    <keycap>I</keycap>
> </keycombo>

i'm uncomfortable with this way of extending keycaps to handle
the additional keys.

the problem is that something like the "escape" key can be used in
two different ways:

1) it can be a "modifier", if you want to call it that, in that it
   can be pressed just before pressing another key, or

2) it can be a separate key press all on its own, such as to
   press "escape" to, say, exit a program

in either case, there should be a way to say, "i want to press
the Escape key here", which logically suggests that there should
be a separate keycap-type entry for "Escape".  

"Escape", or "Alt", or others keys like that, i don't think 
belong simply as attributes of a keycap.  really, they're keys
in their own right and should be treated as such.

i *can* accept the above extension, but it just doesn't sit
totally well with me, although i'm still pondering what i
would do differently.

rday




Hi,
i want to discuss with you about the representation
of a website. in docbook-website it has a tree structure,
am i right?
i think a website can be represented better with a graf,
which has nodes (webpages) and edges (the links). in this
repesentation we can descript a webpage with its content
and the links to other webpages.
semanticaly it belongs to the webpage itself, and we can
do this to put olinks in the webpage header.
i think this representasion is closer to the reality, than
layout's repesented tree structure.
what about this idea?

Gabor.





Hi,

what is the appropriate markup for UNIX signals?

I'm using

<systemitem class="event">SIGUSR2</systemitem>

Is that the correct way? Or is there other markup I've overseen?

Thanks in advance.

Gisbert Amm



-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

/ Elliotte Rusty Harold <elharo@metalab.unc.edu> was heard to say:
| At 7:51 AM -0500 3/12/03, Norman Walsh wrote:
|
|>No. The base URI in both cases is: http://www.example.com/docs/
|>
|>The base URI is not the same as the "document URI".
|
| I agree that would be nicer, and it makes more sense; but it's not my
| reading of either the XML Infoset or the XML Base specification. In
| particular, section 4.1 of the XML Base spec
| <http://www.w3.org/TR/xmlbase/#rfc2396> states,
|
| RFC 2396 [IETF RFC 2396] provides for base URI information to be
| embedded within a document. The rules for determining the base URI can
| be summarized as follows (highest priority to lowest):
|
|     1. The base URI is embedded in the document's content.
|     2. The base URI is that of the encapsulating entity (message,
| document, or none).
|     3. The base URI is the URI used to retrieve the entity.
|     4. The base URI is defined by the context of the application.
|
| Assuminng there's no xml:base attribute in scope, then either 2 or 3
| applies. Both use the base URI of the document itself, not the
| directory where the document is found.  RFC 2396 seems to say the same
| thing. What am I missing?

This stuff is really confusing. It's especially confusing because of
the rules for constructing an absolute URI from a base URI and a
relative URI.

On further reflection, I think you're right. If you're reading documents from
a filesystem, then the base URI of 

   file:///path/to/file1.xml

and

   file:///path/to/file2.xml

are different and are the URIs of the respective documents. Note
however, that if these base URIs are used construct an absolute URI
from some relative reference inside them, they are each effectively
equivalent to file:///path/to/ (per RFC 2396, Section 5.2, list item 6.a).

I think it follows that in another context, the base URI of the two
documents might be the same. In particular, a multi-part MIME message
might encode those files as:

  http://example.com/uri/of/the/mime/package

    Content-base: http://example.com/path/to/
    ...
    <<Separator>>
    Content-location: file1.xml
    ...
    <<Separator>>
    Content-location: file2.xml

in which case the two documents do have precisely the same base-URI.
(If there are persuasive arguments that I'm wrong, I'd love to hear
them because this line of argument lead to a new property in the
XPath2 data model and a new F&O function last Friday.)

In short, returning to your example:

| Suppose for example,
| http://www.example.com/docs/parent.xml includes
| http://www.example.com/docs/child.xml

1. In the absence of other information, it's impossible to know what
   the base URIs of these documents are (since the web server could
   send a content-base header). However, in the common case, I concede
   that they do have different base URIs and those URIs are the full
   URIs of each file.

2. But they certainly could have the same base URI (http://www.example.com/docs/).

3. Effectively, the base URI used for resolving relative URIs in all
   of the three possible values in play are effectively the same for
   that purpose so I'm not sure that libxml is causing any harm by
   leaving out what are essentially redundant base URIs.

4. Any statement made about RFC 2396 that's not *immediately* preceded
   by 20 minutes of reading in the RFC is probably wrong.

                                        Be seeing you,
                                          norm

- -- 
Norman Walsh <ndw@nwalsh.com>      | No man is more than another if he
http://www.oasis-open.org/docbook/ | does no more than
Chair, DocBook Technical Committee | another.--Cervantes
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.0.6 (GNU/Linux)
Comment: Processed by Mailcrypt 3.5.7 <http://mailcrypt.sourceforge.net/>

iD8DBQE+b0RLOyltUcwYWjsRAi3VAJ4yDHslffIXoZqQBgY4dESHcxQTHgCcC9uw
uQR7a4K6tekO446/1pFJyBE=
=n6d5
-----END PGP SIGNATURE-----



Norman Walsh wrote:

> | * 'type' seems to name types, not describe them. What
> |    about a 'typesynopsis' to actually define specific types ?
> 
> Can you show me an example of what you'd like to put in a type synopsis?

imagine code such as

typedef int MyInt;
enum FooBar { FOO = 0, BAR = 1};

I'd like to document that, i.e. the code could contain comments such as

// MyInt is a special integer type used to...
typedef int MyInt;

// FooBar represents the foobar of...
enum FooBar
{
// FOO signifies...
FOO = 0,
// BAR signifies 'not FOO'
BAR = 1
};

and I want to translate that into a document that lists the definition 
(purpose, usage, etc.) of the above types and constants. I want this 
documentation to be at the same level as class definitions 
(classsynopsis etc.) for example.

> | * same for 'variable': what about a 'variablesynopsis' (or 'varsynopsis') ?
> |    And, while we are at it: what is special about a 'field'
> |    (docbook's name for 'member variables') ? If there was a
> |    generic 'variable' element, couldn't 'fieldname' be considered
> |    a specialized 'variable' (or then 'varname') ?
> 
> I suppose. The funcsynopsis stuff was one of DocBook's few forays into
> modeling. After years of requests, we built a classsynopsis element to
> model object oriented languages in a similar way. As a general rule, we've
> tried to avoid modeling in DocBook and there are days when I wish we hadn't
> done either funcsynopsis or classsynopsis :-)

yeah, the current situation looks a bit inconsistent, or at least
unfinished. An example showing how to document APIs would really
help. Having used texinfo for this purpose a number of times, I see a
number of useful features that could be implemented with appropriate
stylesheets, such as the (semi-)automatic generation of indexes for
types, constants, functions, etc.)

> | * again for 'constant': a 'constsynopsis' to contain constant definition
> 
> What sort of definition?

see above. I think UNIX man pages could use these, for example to
contain the definitions for errno codes, or signals, or...

> | * a 'modulesynopsis' to define 'contexts', 'scopes', 'packages' or
> |    whatever this may be called in the various programming languages
> 
> There's already an RFE for package markup. And a longstanding action
> item on me to investigate. The problem is that there many different,
> conflicting notions about what a package is.

Indeed, but as you repeatedly said you didn't want docbook to become
a modeling language, I didn't think it is that important to attach
specific semantics to 'package', beside defining sort of a
context/scope.

> Examples of what you have in mind would be useful.

again, if I have (C++) code defining a namespace, and in that
namespace some other expressions I want to document, I'd like
to be able to document the namespace itself (it's purpose, domain,
etc.) and then put stuff into it. I admit that packages are for
my purposes the least urgent, as I can just map them to 'sections',
though it would be nice to attach a *little* more meaning to it.

Regards,
		Stefan





>>>>> "Robert P. J. Day" <rpjday@mindspring.com>:

> the problem is that something like the "escape" key can be used in
> two different ways:

> 1) it can be a "modifier", if you want to call it that, in that it
>    can be pressed just before pressing another key, or

> 2) it can be a separate key press all on its own, such as to
>    press "escape" to, say, exit a program

I don't see a difference in these two usages from a markup point of
view.  Both are single presses of the escape key as far as I, and the
docbook manual representing the keypress, can tell...?



-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

/ Baráth Gábor <dincsi@elender.hu> was heard to say:
| i want to discuss with you about the representation
| of a website. in docbook-website it has a tree structure,
| am i right?

The principle navigation structure is a tree.

| i think a website can be represented better with a graf,
| which has nodes (webpages) and edges (the links). in this
| repesentation we can descript a webpage with its content
| and the links to other webpages.

There's nothing about website that prevents (or discourages) links
between pages independent of the primary hierarchy. In fact, I do it
all the time. With olinks, even:

  <para>This area identifies
  <olink targetdocent="books.xml">books</olink>,

| semanticaly it belongs to the webpage itself, and we can
| do this to put olinks in the webpage header.
| i think this representasion is closer to the reality, than
| layout's repesented tree structure.
| what about this idea?

Go for it. One of the things that motivated website was a desire to
impose an ordered structure on the site. If you have a different
structure in mind, explore it and let us know where you end up.

                                        Be seeing you,
                                          norm

- -- 
Norman Walsh <ndw@nwalsh.com>      | The average man, who does not know
http://www.oasis-open.org/docbook/ | what to do with his life, wants
Chair, DocBook Technical Committee | another one which will last
                                   | forever.--Anatole France
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.0.6 (GNU/Linux)
Comment: Processed by Mailcrypt 3.5.7 <http://mailcrypt.sourceforge.net/>

iD8DBQE+b0q3OyltUcwYWjsRAnOVAKCZeh/n4yQHBjE+4MKDiPpDD14jxQCeISoN
Ju7gPdJBUAot3UXG8Iovq3I=
=KrdJ
-----END PGP SIGNATURE-----



-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

/ Gisbert Amm <gia@webde-ag.de> was heard to say:
| what is the appropriate markup for UNIX signals?
|
| I'm using
|
| <systemitem class="event">SIGUSR2</systemitem>
|
| Is that the correct way? Or is there other markup I've overseen?

That looks fine to me.

                                        Be seeing you,
                                          norm

- -- 
Norman Walsh <ndw@nwalsh.com>      | It does not do harm to the mystery
http://www.oasis-open.org/docbook/ | to know a little about it. For far
Chair, DocBook Technical Committee | more marvelous is the truth than
                                   | any artists of the past
                                   | imagined!--Richard Feynman
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.0.6 (GNU/Linux)
Comment: Processed by Mailcrypt 3.5.7 <http://mailcrypt.sourceforge.net/>

iD8DBQE+b0ryOyltUcwYWjsRAiAIAJ92MKJ87WRCG7f8D56B5JDn98/oOwCeL3Ik
T9Z0tkRLh3d1N5XY8FmesSM=
=Vi0P
-----END PGP SIGNATURE-----



On Wed, 12 Mar 2003, Steinar Bang wrote:

> >>>>> "Robert P. J. Day" <rpjday@mindspring.com>:
> 
> > the problem is that something like the "escape" key can be used in
> > two different ways:
> 
> > 1) it can be a "modifier", if you want to call it that, in that it
> >    can be pressed just before pressing another key, or
> 
> > 2) it can be a separate key press all on its own, such as to
> >    press "escape" to, say, exit a program
> 
> I don't see a difference in these two usages from a markup point of
> view.  Both are single presses of the escape key as far as I, and the
> docbook manual representing the keypress, can tell...?

sorry, i guess i wasn't clear -- i actually agree with you, which
is why i think keystrokes like "Esc" need to be a separate
element.

i remember some of the earlier proposals that had these kinds
of keys strictly as attributes for a "regular" keycap element,
which i didn't much like.

and because they are discrete keystrokes in their own right,
i don't think supporting them with a "function" attribute
quite fits the bill.

just my $.02.

rday




Robert P. J. Day wrote:

> On Wed, 12 Mar 2003, Tobias Reif wrote:
> 
>><keycombo action="simul">
>>   <keycap function="control"/>
>>   <keycap function="alt"/>
>>   <keycap function="backspace"/>
>></keycombo>
>>
>><keycombo action="simul">
>>   <keycap function="alt"/>
>>   <keycap function="shift"/>
>>   <keycap>I</keycap>
>></keycombo>
>>
> i'm uncomfortable with this way of extending keycaps to handle
> the additional keys.
> 
> the problem is that something like the "escape" key can be used in
> two different ways:
> 
> 1) it can be a "modifier", if you want to call it that, in that it
>    can be pressed just before pressing another key, or


<keycombo action="simul">
           ^^^^^^^^^^^^^^
    <keycap function="escape"/>
    <keycap function="a"/>
</keycombo>


> 2) it can be a separate key press all on its own, such as to
>    press "escape" to, say, exit a program


  <keycap function="escape"/>


> in either case, there should be a way to say, "i want to press
> the Escape key here", which logically suggests that there should
> be a separate keycap-type entry for "Escape".  


see above


> "Escape", or "Alt", or others keys like that, i don't think 
> belong simply as attributes of a keycap.  really, they're keys
> in their own right and should be treated as such.


    <keycap function="escape"/>

In english "The keycap with function escape." or "The keycap providing 
the functinality named escape."


> i *can* accept the above extension, but it just doesn't sit
> totally well with me, although i'm still pondering what i
> would do differently.


Do some more pondering :) , but I don't see your point as argument 
against the suggested syntax/naming.

Other suggestions (which would also be OK IMHO) looked like

   <input action="escape"/>
or
   <input type="escape"/>
or
   <action type="escape"/>
or
   <action name="escape"/>

Also check the RFE page (RFE  697374)
http://sourceforge.net/tracker/index.php?func=detail&aid=697374&group_id=21935&atid=384107


Tobi


-- 
http://www.pinkjuice.com/




Robert P. J. Day wrote:


> sorry, i guess i wasn't clear -- i actually agree with you, which
> is why i think keystrokes like "Esc" need to be a separate
> element.


I don't think that everything needs be represented by a separate 
element. See for example the example in the spec
tdg-en-html-2.0.7/tdg/en/html/systemitem.html :

   <systemitem class="systemname">helio.oreilly.com</systemitem>

"h" (not as char, but as key) doesn't have an element either, but is 
written as

   <keycap>h</keycap>


> i remember some of the earlier proposals that had these kinds
> of keys strictly as attributes for a "regular" keycap element,
> which i didn't much like.


Why not? The typical way to do "enter" is to press
   the key with function "enter".
This translates nicely to
   <keycap function="enter"/>


> and because they are discrete keystrokes in their own right,
> i don't think supporting them with a "function" attribute
> quite fits the bill.


I think that it actually is a quite concise way of expressing/marking up 
function keys. Also see the other reply.


Tobi


-- 
http://www.pinkjuice.com/




> / Gisbert Amm <gia@webde-ag.de> was heard to say:
> | what is the appropriate markup for UNIX signals?
> |
> | I'm using
> |
> | <systemitem class="event">SIGUSR2</systemitem>
> |
> | Is that the correct way? Or is there other markup I've overseen?
> 
> That looks fine to me.
> 
>                                         Be seeing you,
>                                           norm
Thanx,
Gisbert




  i didn't mean to make a big issue out of this; i'm satisfied
with the current proposal, but let me just try to explain what
i was talking about -- it might make sense, it might not.

  currently, a key cap is written as <keycap>x</keycap>.  this
seems to suggest that a keycap is, by default, of type "literal",
if i can call it that.  and its content is "x".  so far, so good?
(one might even go as far as to suggest that the above really
represents the element <keycap type="literal">x</keycap>, where
obviously i am *inventing* the mythical "type" attribute, and making
it the default.)

  so how would one represent a *non-literal* key?  extending
the above, perhaps as <keycap type="function">Escape</keycap>,
or something to that effect.  in writing it this way, i'm trying
to separate the *kind* of keystroke from its *content*, because i
see those two pieces of information as, in some way, orthogonal.

  now the above is pretty darn wordy, but one can condense it
by, perhaps, redefining keycap to not need any content at all:

  <keycap literal="x"/>
  <keycap function="escape"/>

this, at least, is a consistent definition of a keycap -- it has
to specify both a *type* of key, and its associated content (that is,
the attribute and its value).

  i also notice that the definition of a keycap, according to 
2.0.8, is "the *text* printed on a key on the keyboard" (my emphasis).
notice that this isn't strictly true anymore, since what might be
displayed could be something other than text.

  anyway, i realize i'm being thoroughly anal retentive, so i'll just
shut up now, and whole-heartedly support whatever gets added.

rday




On Wed, Mar 12, 2003 at 10:42:01AM -0500, Robert P. J. Day wrote:

>   currently, a key cap is written as <keycap>x</keycap>.  this
> seems to suggest that a keycap is, by default, of type "literal",
> if i can call it that.  and its content is "x".  so far, so good?
> (one might even go as far as to suggest that the above really
> represents the element <keycap type="literal">x</keycap>, where
> obviously i am *inventing* the mythical "type" attribute, and making
> it the default.)

I always understood <keycap> to mean the actual writing on the
physical key.  Of course, <keycap/> probably isn't a good way
of describing the space bar.. ;-)

Tim.
*/

PGP signature



Nested procedures, procedures inside of tables, etc. would be messy--not
sure how you'd number them. <substeps> allows you to nest procedures
without that problem. I think no procedures in paras is a good thing.

David

-----Original Message-----
From: Norman Walsh [mailto:ndw@nwalsh.com] 
Sent: Wednesday, March 12, 2003 6:43 AM
To: docbook mailing list
Subject: DOCBOOK: Re: any reason why a "procedure" is not a child of
"para"?

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

/ "Robert P. J. Day" <rpjday@mindspring.com> was heard to say:
|   i just noticed that the procedure element cannot be a child
| of a para, as can other lists.  any reason for this?  it seems
| like this would be useful if a procedure should be considered
| part of its enclosing paragraph.  just curious.

I don't recall consciously deciding to exclude it. File an RFE, I guess.

                                        Be seeing you,
                                          norm

- -- 
Norman Walsh <ndw@nwalsh.com>      | Debugging is 99% complete most of
http://www.oasis-open.org/docbook/ | the time--Fred Brooks, jr.
Chair, DocBook Technical Committee |




On Wed, 12 Mar 2003, David Cramer wrote:

> Nested procedures, procedures inside of tables, etc. would be messy--not
> sure how you'd number them. <substeps> allows you to nest procedures
> without that problem. I think no procedures in paras is a good thing.

i don't follow this logic.  in a way, a procedure is just another
kind of list, if you want to look at it that way.  and, certainly,
all of the list-type elements can be children of paras.

way back when i was just getting into docbook, i asked whether
folks recommended making a list a child of a para, or the next
sibling element.  the response was to consider whether the
list and the para were inherently linked, so that it made no
sense to have one without the other.

consider a possible para:

  <para>If you want to start writing in DocBook, here are the
   steps you'll need to do:
   <procedure>
    ....
   </procedure>
  </para>

this makes perfect sense, and it's clear that the <procedure>
element logically belongs within the paragraph.

*note*: i'm not saying that procedures *must* be children of
paragraphs, obviously.  only that, to be consistent with the
other lists, it should have the option.

rday




Robert P. J. Day wrote:

>   i didn't mean to make a big issue out of this; i'm satisfied
> with the current proposal,


cool :)


>   currently, a key cap is written as <keycap>x</keycap>.  this
> seems to suggest that a keycap is, by default, of type "literal",
> if i can call it that.


Yep, and this stays true for "non-function"/char keys.


>   now the above is pretty darn wordy, but one can condense it
> by, perhaps, redefining keycap to not need any content at all:
> 
>   <keycap literal="x"/>
>   <keycap function="escape"/>


In
  <keycap>x</keycap>
the textual content is literal, which is implied (as you wrote above), 
and understood.
So
  <keycap>x</keycap>
  <keycap function="escape"/>
makes sense IMHO.


>   i also notice that the definition of a keycap, according to 
> 2.0.8, is "the *text* printed on a key on the keyboard" (my emphasis).


yep (notice that currently there is a problem, since on my control key, 
there is written "Strg", while on other's there's "Ctrl")


> notice that this isn't strictly true anymore,


Exactly, but it stays true for "non-function"/char keys.

For stuff like
  <keycap>x</keycap>
the def stays true.
For the proposed extension, the spec would need to be extended to 
explain the notation for those keycaps which are function keys, eg 
<keycap function="escape"/> for escape etc.

 >  since what might be
 > displayed could be something other than text.

Exactly! That's one of the main reasons for requesting that the markup 
for function keys be specified/standardized, no matter which 
notation/naming/syntax is used. Then you can translate them into pics, 
ASCII rendering, foreign laguages, etc.


>   anyway, i realize i'm being thoroughly anal retentive, so i'll just
> shut up now, and whole-heartedly support whatever gets added.


Discussing this stuff makes sense. Thanks for your input.


Tobi


-- 
http://www.pinkjuice.com/




Tim Waugh wrote:


> I always understood <keycap> to mean the actual writing on the
> physical key.


Makes sense for character keys; see the other posts.

> Of course, <keycap/> probably isn't a good way
> of describing the space bar.. ;-)


Yes it isn't; there is no space character included.

Probably
   <keycap> </keycap>
is a better way.

A more robust way (concering whitespace handling in XML tools) might be 
to allow

   <keycap function="space"/>

but this is only a workaround for whitespace issues since the space key 
(typically) isn't a function key.


Tobi


-- 
http://www.pinkjuice.com/




Here's my 2 cents:

I see no reason that a procedure should be a child of a paragraph. The 
paragraph immediately preceding a procedure would reference that 
procedure. Why would one need to put a procdure inside a paragraph?

This is clear:

...To install the software perform the following procedure:

1. Insert the installation disk in the drive.
2. Another step

This is not so clear:

...To install the software: 1. Insert the installation disk in the 
drive. 2. Allow the setup program to launch. If it does not launch you....

Placing a procedure within a table doesn't add much but could provide a 
better indication of where the procedure starts and stops because of the 
table's lines. I was forced to do this when working for a customer to 
satisfy their "updated" template for a new "look and feel". The left 
column of each row provided the step number and the right column 
provided the instructions. It could also be done for a single column 
table so that each step is contained within a cell. Providing for a 
procedure within a single column table appears to be rather messy for 
the small visual benefit though.

Jeff Biss



There seems

David Cramer wrote:

>Nested procedures, procedures inside of tables, etc. would be messy--not
>sure how you'd number them. <substeps> allows you to nest procedures
>without that problem. I think no procedures in paras is a good thing.
>
>David
>
>-----Original Message-----
>From: Norman Walsh [mailto:ndw@nwalsh.com] 
>Sent: Wednesday, March 12, 2003 6:43 AM
>To: docbook mailing list
>Subject: DOCBOOK: Re: any reason why a "procedure" is not a child of
>"para"?
>
>-----BEGIN PGP SIGNED MESSAGE-----
>Hash: SHA1
>
>/ "Robert P. J. Day" <rpjday@mindspring.com> was heard to say:
>|   i just noticed that the procedure element cannot be a child
>| of a para, as can other lists.  any reason for this?  it seems
>| like this would be useful if a procedure should be considered
>| part of its enclosing paragraph.  just curious.
>
>I don't recall consciously deciding to exclude it. File an RFE, I guess.
>
>                                        Be seeing you,
>                                          norm
>
>- -- 
>Norman Walsh <ndw@nwalsh.com>      | Debugging is 99% complete most of
>http://www.oasis-open.org/docbook/ | the time--Fred Brooks, jr.
>Chair, DocBook Technical Committee |
>
>
>
>





On Wed, 12 Mar 2003, Jeff Biss wrote:

> Here's my 2 cents:
> 
> I see no reason that a procedure should be a child of a paragraph. The 
> paragraph immediately preceding a procedure would reference that 
> procedure. Why would one need to put a procdure inside a paragraph?

for exactly the same reason that someone would put a list inside
a paragraph -- because it inherently forms some of the content of
that paragraph.

it's not unusual for an XML editor to allow you to expand/collapse
elements, and to move thoselelements to another part of the document.
currently, when i make lists in emacs in outline mode, i can do that.

if the procedure is a child element of a <para>, it means that i 
can logically move a paragraph, and its contents (including the
procedure to which it refers) comes along for the ride.
if that's not true, i then must move *both* elements, even when
they're clearly related.

keep in mind that this is the way it was explained to *me*
originally when i asked about the efficacy of those two
approaches.  it made sense then, and it still makes sense now.

conversely, if you don't like this for procedures, by the same
logic, you would have to argue against it for all of the
list-type elements as well.

i'm just trying to be consistent.

rday

p.s.  yes, i really have other things i could be doing. :-)




Ah, I see that procedures can be inside things that can be in procedures
etc (listitem, admons). It never occurred to me to try that. Never mind.


David 

-----Original Message-----
From: Jeff Biss [mailto:jeff@marco-inc.com] 

Placing a procedure within a table doesn't add much but could provide a 
better indication of where the procedure starts and stops because of the

table's lines. I was forced to do this when working for a customer to 

David Cramer wrote:

>Nested procedures, procedures inside of tables, etc. would be
messy--not
>sure how you'd number them. <substeps> allows you to nest procedures
>without that problem. I think no procedures in paras is a good thing.
>
>David

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Powered by ezmlm-idx