Re: docs layout revision

[André Malo <nd...@perlig.de>]

* Joshua Slive wrote:

>> ok. we revised the whole stuff. It might be a little bit colorful
>> now, but IMHO it becomes also more friendly so.
> 
> OK.  I'll try to find a little time to do an xsl mockup of this
> stuff. 

If there are any questions in conclusion with the layout or the
semantics, please ask. Maybe some parts (of my thoughts :) need an
explanation. 
And probably are there some things I not thought about in the CSS
(because some parts of the documentation are a little bit loose, we
will see the problems, if there ary any, after the whole
transformation) 

>> There are several semantics issues, which we should think over. For
>> instance, the <em>s used in syntax definitions should be <var>s.

> Yes, true.

ok, if no other does, I'm going to look through the documents and
patch them.

(Do we need to modify the dtds?)

>> | The processing is controlled by specially formated SGML comments,
>> | referred to as <em>elements</em>.
>>
>> is probably better written as "... <dfn>elements</dfn>."
> 
> I'm not exactly sure what you are implying here.  What specifically
> does <dfn> mean semantically?

from html spec:

| [dfn] indicates that this is the defining instance of the enclosed
| term. 

in the words of the example above: The author explains, what elements
are. So the [by dfn] enclosed term "elements" is the defining
instance. 

> The other one I was thinking of adding which is somewhat related is
> some kind of tag to indicate that something is defined in the
> glossary (which the xsl could automatically transform into a link to
> the relevant place in the glossary).

<glossary>? ;-)

it could result in
<a href="glossary.html#blah" title="glossary">blah</a> or so.

perhaps with an image before (an arrow that points right up).

> And another one is that <code> might be overused in some places
> where a more specific tag would be better.  I haven't thought too
> much about what could replace it.

in XML or HTML?

hmm. in HTML there are <samp> and <kbd> additionally possible.

| SAMP: Designates sample output from programs, scripts, etc. 
| KBD: Indicates text to be entered by the user. 

IMHO <samp> may be used for sample input, too.
<kbd> is a problem in our case, because nearly all of the code there
has to be entered by the user... ;-) 

nd
-- 
print "Just Another Perl Hacker";

# André Malo, <http://www.perlig.de/> #

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org