[drupal-docs] Good stuff: clearly written docs

[puregin]

On 22 Apr 2005, at 9:59 PM, Steven Wittens wrote:

>
>> Just checked.  Much easier to read.  The faint blue highlight is 
>> definitely a nice touch (you could even go a shade or two darker).
>
> Well there are really two uses of <code>... when used for multiple 
> lines of text, a separate code box is created. When used for a single 
> piece of text, it is used inline and only the font was changed. Often 
> however the inline use was also used to emphasise bits of text, and 
> the background helps with that.
>
> Which kinds of text to include in <code> is of course something up for 
> discussion ;). If needed I can create some more specific styles / 
> classes for use in documentation, though I don't think we'll need 
> those much in Drupal. A common example is to give keyboard key names a 
> 3D button look.

     Let's try to discourage overloading of <code>.    There's a variety 
of other options we could use
for particular situations:  <kbd>, <pre>, <blockquote>, <var> , <abbr>, 
  <acronym>,  <cite>, <samp>.
I'd suggest:  <kbd> for keystrokes,  <samp> for literal output, <var> 
for variable names, command names,
etc., <tt> for literal input.

    It might be useful to think about flagging filenames consistently, 
and also
dummy parameters (which need to be replaced by actual values) in 
examples.


>
> There is also a slight problem with tables in the documentation, in 
> that table rows require alternating "dark" "light" classes to appear 
> striped. I'll see if I can write a striping filter which does this 
> automatically for tables inside content.
>
> Steven Wittens
> -- 
> [ drupal-docs | http://lists.drupal.org/listinfo/drupal-docs ]
>
--
Djun M. Kim, Director                           
djun.kim at cielosystems.com
Cielo Systems Inc.                              
http://www.cielosystems.com
Strategic Software Research                     Tel:   (604) 739-3941
302 - 1298 10th Avenue West                     FAX:   (604) 739-3943
Vancouver, BC, V6H 1J4                          Mobile:(778) 895-1379