CTR notice: htdocs/manual/mod edits

[Rodent of Unusual Size <Ke...@Golux.Com>]

Just so you know..  I'm about to embark on a big edit through
the module documentation files to turn the directive attributes
(Syntax, Default, Context, ...) into links to the attribute
definitions in mod/directive-dict.html.  (See the example module
documentation: <http://www.apache.org/docs/mod/mod_example.html>.)

I've been threatening to do this for a while, so here goes..

#ken	P-)}

Re: CTR notice: htdocs/manual/mod edits

[Rodent of Unusual Size <Ke...@Golux.Com>]

Rodent of Unusual Size wrote:
> 
> Just so you know..  I'm about to embark on a big edit through
> the module documentation files to turn the directive attributes
> (Syntax, Default, Context, ...) into links to the attribute
> definitions in mod/directive-dict.html.  (See the example module
> documentation: <http://www.apache.org/docs/mod/mod_example.html>.)

Oh, and I'm going to do a lot of normalisation of HTML tags
to uppercase (e.g., <em> -> <EM> and so on).  No-one writing or
modifying the documentation should feel constrained to maintain
this convention, but I may make periodic passes through to
change any discrepancies.

#ken	P-)}

Re: CTR notice: htdocs/manual/mod edits

[Brian Behlendorf <br...@organic.com>]

At 10:32 AM 1/26/98 -0500, you wrote:
>Did you look at the mod_example.html page to see what I meant?  

Yes, I had.  I guess we just have a difference of opinion.  Not worth
fighting about, but I am interested in hearing what others think.  

Also, it would be good to have an HTML style guide document...

	Brian

 
--=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=--
specialization is for insects				  brian@organic.com

Re: CTR notice: htdocs/manual/mod edits

[Rodent of Unusual Size <Ke...@Golux.Com>]

Brian Behlendorf wrote:
> 
> Speaking personally, I really don't like the idea.  I'm sorry for missing
> your previous threats :) but I think from a hypertext perspective it could
> lead to a lot of confusion and visual clutter.  To go to the extreme
> example: what if we made every mention of "directive" a link to a
> dictionary definition of directive?  Very quickly we could go down a
> slippery slope towards making half the words in the documentation links to
> their definitions or documentation...

Did you look at the mod_example.html page to see what I meant?  We have
lots and lots of pointers to mumble.html#foodirective in the online
documentation and elsewhere.  When you follow one of those to the
directive description, you can see what the directive does, but the
boldface attributes are frequently cryptic and inconsistently used.
There was no one place (AFAIR) where what they meant was documented,
which is why directive-dict.html was put in quite a while ago.

Yes, it's visually cluttering when you read something like core.html
top to bottom - but if you've followed a link to the one particular
directive you want to use, it seems reasonable to make its description
as complete as possible.

#ken	P-)}

Re: CTR notice: htdocs/manual/mod edits

[Brian Behlendorf <br...@organic.com>]

At 10:04 AM 1/25/98 -0500, Rodent of Unusual Size wrote:
>Just so you know..  I'm about to embark on a big edit through
>the module documentation files to turn the directive attributes
>(Syntax, Default, Context, ...) into links to the attribute
>definitions in mod/directive-dict.html.  (See the example module
>documentation: <http://www.apache.org/docs/mod/mod_example.html>.)
>
>I've been threatening to do this for a while, so here goes..

Speaking personally, I really don't like the idea.  I'm sorry for missing
your previous threats :) but I think from a hypertext perspective it could
lead to a lot of confusion and visual clutter.  To go to the extreme
example: what if we made every mention of "directive" a link to a
dictionary definition of directive?  Very quickly we could go down a
slippery slope towards making half the words in the documentation links to
their definitions or documentation...

	Brian


--=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=--
specialization is for insects				  brian@organic.com