Is there any preferred way for using html markup for tagging module names, parameter names, and flags in the document html pages?
From what I have seen, <b>, <em>, and <i> (or some combination thereof) have been variously used to highlight module names, flags and parameters. Although flags seem to be more consistently <b>oldfaced than anything else.
For the sake of consistency between pages, and for a common look, I would like to adhere to a common rationale for using html markup on these descriptors.
My own preference is to just boldface flags and parameter names; that seems to make them stand out better when scanning quickly through the page, more so than <em>phasis.
Is there any preferred way for using html markup for tagging module names, parameter names, and flags in the document html pages?
AFAIK not really. It would be reasonable to define these rules and
update SUBMITTING_DOCS document accordingly.
>From what I have seen, <b>, <em>, and <i> (or some combination thereof) have been variously used to highlight module names, flags and parameters. Although flags seem to be more consistently <b>oldfaced than anything else.
For the sake of consistency between pages, and for a common look, I would like to adhere to a common rationale for using html markup on these descriptors.
My own preference is to just boldface flags and parameter names; that seems
to make them stand out better when scanning quickly through the page, more so than <em>phasis.
+1 for <b>flag</b> and <b>name</b>
* <em>module</em> or <em><a href="module.html">module</em> for
external references
Is there any preferred way for using html markup for tagging module names, parameter names, and flags in the document html pages?
M:
AFAIK not really. It would be reasonable to define these rules and
update SUBMITTING_DOCS document accordingly.
>From what I have seen, <b>, <em>, and <i> (or some combination thereof) have been variously used to highlight module names, flags and parameters. Although flags seem to be more consistently <b>oldfaced than anything else.
For the sake of consistency between pages, and for a common look, I would like to adhere to a common rationale for using html markup on these descriptors.
My own preference is to just boldface flags and parameter names; that seems
to make them stand out better when scanning quickly through the page, more so than <em>phasis.
+1 for <b>flag</b> and <b>name</b>
By name, you meant any module parameter?
* <em>module</em> or <em><a href="module.html">module</em> for
external references
2008/2/24, Patton, Eric <epatton@nrcan.gc.ca>:
[snip]
>> My own preference is to just boldface flags and parameter names; that seems
>> to make them stand out better when scanning quickly through the page, more so than <em>phasis.
Is there any preferred way for using html markup for tagging module
names, parameter names, and flags in the document html pages?
From what I have seen, <b>, <em>, and <i> (or some combination
thereof) have been variously used to highlight module names, flags
and parameters. Although flags seem to be more consistently
<b>oldfaced than anything else.
For the sake of consistency between pages, and for a common look, I
would like to adhere to a common rationale for using html markup on
these descriptors.
My own preference is to just boldface flags and parameter names; that
seems to make them stand out better when scanning quickly through the
page, more so than <em>phasis.
The common usage has been:
module names <em>
flags and option names <b> (inline text; not within <pre> code)
shell commands, names, etc <tt> (inline text; don't overuse)
emphasized phrase <i> (inline text; use instead of bolding the
sentence)
code: <div class="code"><pre> ... </pre></div>
I have never really had a good answer for that: for a few entries all
on one line looks ok, for many entries it is much easier to scan down a
one module per line. In general Markus has put them across, I have put
them one per line. shrug, just a matter of preference I guess.
In general SEE ALSO modules are listed in alphabetical order, but
sometimes important ones have been put first. shrug.
If referencing external software or PDF/PostScript guides linked from
the website put a paragraph break between them and the modules (modules
come first).
I expect there are many dead links to non-ported GRASS 5 modules and
many help pages may talk of obsolete interactive mode.
Hamish
____________________________________________________________________________________
Never miss a thing. Make Yahoo your home page. http://www.yahoo.com/r/hs
I've been removing obsolete references to the old interactive mode
from the docs as I encounter them.
some modules do actually still have interactive modes available, so
don't just remove blindly. In the past I have <!-- commented out -->
sections I wasn't sure about until pouring through the module code.
Also, although g.html2man attempts to handle tables, it doesn't seem
to work. Please remove <TABLE> <TD> <TH> from the list of allowed
tags.
Tables can be useful. I would think it better to try and improve
g.html2man if the current implementation is not working well, rather
than ban them.
Hamish
____________________________________________________________________________________
Never miss a thing. Make Yahoo your home page. http://www.yahoo.com/r/hs
some modules do actually still have interactive modes available, so
don't just remove blindly. In the past I have <!-- commented out -->
sections I wasn't sure about until pouring through the module code.
Right, of course. I've encountered a few of these commented sections
already and left them unaltered for future demystifying. In a few cases
I have inserted a few of my own to make some edits clear.
Is there any preferred way for using html markup for tagging module names,
parameter names, and flags in the document html pages?
>From what I have seen, <b>, <em>, and <i> (or some combination thereof)
> have been variously used to highlight module names, flags and parameters.
> Although flags seem to be more consistently <b>oldfaced than anything
> else.
For the sake of consistency between pages, and for a common look, I would
like to adhere to a common rationale for using html markup on these
descriptors.
My own preference is to just boldface flags and parameter names; that seems
to make them stand out better when scanning quickly through the page, more
so than <em>phasis.
Feedback welcome,
~ Eric.
Eric,
I wonder if now would be a good time to investgate the use of CSS in the man
pages. If we define a couple types of "container" objects (<div>, <span>,
etc) we can use a single style file to later manipulate the look and feel of
the manual pages. Something like this:
<div class="module_description">
...
</div>
<div class="module_inputs">
...
</div>
I am not CSS expert, but it would seem that we could easily create a set of
classes - or class hierarchy to allow global changes to the style of the
manual. The self-documenting 'class' operator might be helpful as well.
I wonder if now would be a good time to investgate the use of CSS in the man
pages. If we define a couple types of "container" objects (<div>, <span>,
etc) we can use a single style file to later manipulate the look and feel of
the manual pages. Something like this:
<div class="module_description">
...
</div>
<div class="module_inputs">
...
</div>
I am not CSS expert, but it would seem that we could easily create a set of
classes - or class hierarchy to allow global changes to the style of the
manual. The self-documenting 'class' operator might be helpful as well.
> Also, although g.html2man attempts to handle tables, it doesn't seem
> to work. Please remove <TABLE> <TD> <TH> from the list of allowed
> tags.
Tables can be useful.
They might be useful if they worked.
I would think it better to try and improve
g.html2man if the current implementation is not working well, rather
than ban them.
While it would be better if tables worked, the current situation where
they don't work (at all, AFAICT) but get used anyhow is worse than
simply not using them.
Look at the lrs(1) or r.in.xyz(1) manpages; the table portions are
garbage. This is the "man lrs" output corresponding to the table in
lrs.html:
LRS table structure
| AttributeTypeDescription | rsid integer reference segment ID, unique
in the table | lcat integer category of the line in the LRS map | lid
integer route ID (LID) | start_map double precision distance measured
along the line in LRS map from the beginning of the line to the begin-
ning of the segment (absolute milepost distance) | end_map double pre-
cision distance measured along the line in LRS map from the beginning
of the line to the end of the segment (absolute distance of subsequent
milepost) | start_mp double precision milepost number assigned to the
start of the segment | start_off double precision distance from
start_mp to the start of the segment measured along the physical object
| end_mp double precision milepost number assigned to the end of the
segment | end_off double precision distance from end_mp to end of the
segment measured along the physical object | end_type integer1: the
same as specified for from_ ; 2: calculated from map along the line
from previous MP; 3: defined by user
Given that Python has at least two HTML parsers as part of its
standard library, we would probably be better off replacing g.html2man
with a Python script which uses one of them. The ad-hoc regex-based
approach used by g.html2man will inevitably only accept an ill-defined
subset of HTML.
Sorry for being from year 2008, but how many GRASS users still use man
pages to read how to use GRASS modules? There are some really good
text-based web browsers (links - my favorite), that support tables
etc. thus eliminating need of man pages at all.
> > Also, although g.html2man attempts to handle tables, it doesn't seem
> > to work. Please remove <TABLE> <TD> <TH> from the list of allowed
> > tags.
>
> Tables can be useful.
I wonder if now would be a good time to investgate the use of CSS in
the man pages. If we define a couple types of "container" objects
(<div>, <span>, etc) we can use a single style file to later
manipulate the look and feel of the manual pages.
...
I am not CSS expert, but it would seem that we could easily create a
set of classes - or class hierarchy to allow global changes to the
style of the manual. The self-documenting 'class' operator might be
helpful as well.
It is already in place:
$ head -n 7 dist.i686-pc-linux-gnu/docs/html/r.random.html
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>GRASS GIS: r.random</title>
<meta http-equiv="Content-Type" content="text/html;
charset=iso-8859-1">
<link rel="stylesheet" href="grassdocs.css" type="text/css">
</head>
notice how the <H2> text is already green+sans? and all the <div
class=code> sections in the examples?
grassdocs.css is in tools/
I see no compelling reason to add a new class for module names, etc.
K.I.S.S.
Dylan Beaudette wrote:
> I wonder if now would be a good time to investgate the use of CSS in
> the man pages. If we define a couple types of "container" objects
> (<div>, <span>, etc) we can use a single style file to later
> manipulate the look and feel of the manual pages.
...
> I am not CSS expert, but it would seem that we could easily create a
> set of classes - or class hierarchy to allow global changes to the
> style of the manual. The self-documenting 'class' operator might be
> helpful as well.
It is already in place:
$ head -n 7 dist.i686-pc-linux-gnu/docs/html/r.random.html
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>GRASS GIS: r.random</title>
<meta http-equiv="Content-Type" content="text/html;
charset=iso-8859-1">
<link rel="stylesheet" href="grassdocs.css" type="text/css">
</head>
notice how the <H2> text is already green+sans? and all the <div
class=code> sections in the examples?
grassdocs.css is in tools/
I see no compelling reason to add a new class for module names, etc.
K.I.S.S.
Hamish
Thanks for the reminder. My original post was mostly about block elements, but
keeping it simple might be more important.
Sorry for being from year 2008, but how many GRASS users still use man
pages to read how to use GRASS modules? There are some really good
text-based web browsers (links - my favorite), that support tables
etc. thus eliminating need of man pages at all.
Call me old fashioned, but I do like my man pages.
'man d.vect' just is faster to type than 'g.manual d.vect'...
I've changed SUBMITTING_DOCS, adding the new guidelines for tags that I posted(<em>,<b>,<i>).
I haven't removed any of the recommended tags, until the dust settles on the discussion.
I've changed SUBMITTING_DOCS, adding the new guidelines for tags that
I posted(<em>,<b>,<i>).
FWIW, I don't know if any modern web browsers treat <em> and <i> tags
differently, but using <em> may be helpful if we decide to do a massive
search and replace to some CSS div style some time in the future.
Hamish
____________________________________________________________________________________
Never miss a thing. Make Yahoo your home page. http://www.yahoo.com/r/hs