[humanmarkup-comment] Legend/Notes on Documents

[Rex Brooks <rexb@starbourne.com>]

Hi Everyone,

I was about to send another list of notes about the documents I have 
been working on to Kurt for his use as he works on putting our core 
documents into a complete XML format from raw text to generic XML to 
an XSLT  transition version to the penultimate presentation or 
display document in XHMTL, when it occurred to me that I ought post a 
more complete list of these notes as a kind of Map Legend, to use a 
metaphor for the process of creating the first working draft versions 
of these documents.

As a Graphic Designer and Web Designer involved with computer 
applications for Advertising and Collateral Materials from before the 
advent of the PC, when I learned typesetting to put myself through 
some post graduate vocational schooling in the days when punched 
paper tape was produced to program a hulking phototypesetting unit, I 
have a long history of learning these technologies as they have come 
along, as well as helping invent them, so a lot of very simple 
methods come to me as second nature. It seldom occurs to me that 
others don't have that kind of background, so don't understand why I 
write html from scratch or work on documents as text-only ascii 
documents until it is time to actually format them for presentation.

In short, it is just easier in the long run to work that way. It 
prevents unnecessary steps to delete all the coding bloat from word 
processors and html editors all of which have been made supposedly 
foolproof by wysiwyg interfaces, all of which just complicate the 
bleep outa some otherwise rather simple and straightforward tasks.

Now Kurt also happens to have a background in typesetting, which may, 
as it was for me, have been his practical introduction to and 
initiation into the mysteries of computer technology, so all this 
explanation is obviously not for his benefit, but for yours, dear 
listmembers.

In the documents I used all caps for major headings or entries/titles 
of major categories in HM.frameworks, and as term names in 
HMI.glossary,  following the practice started by Ranjeeth and Joe 
when they amalgamated these documents in preparation for the work we 
are doing now. These are offset from the rest of the text by strings 
of dashes or hyphens, like this:

--------------------
NAME
--------------------

In all documents so far I then use square parantheses, also called 
brackets to give working definitions for the terms, and these 
definitions are included within the dash-string delimiters like this:

---------------------
NAME OF SOMETHING [definition of something is then given without 
initial upper case letters or punctuation marks other than a comma, 
used in its normal grammatical manner, and a semicolon; used thus to 
show either an example of use or a secondary or corollary definition]
----------------------

eEgular parentheses are just like regular parentheses, not indicating 
anything other than normal parenthetical remarks.

In the HM.frameworks document I also adopted several other practices, 
specifically citing sources, giving their urls and stating that 
direct quotes from sources acutally are delimited by quotation marks. 
In practice, working in raw text doesn't allow for consistently using 
boldface, italic and boldface italic for further delineations in 
various tools like simple text and wordpad/notepad, all of which I 
use depending on which machine is under my fingertips, so I can just 
say that I meant the quoted material to be italicized, with 
references within quotes to published works in regular or non-italic, 
non-bold within the quotes only, with cited references italicized 
when simply cited outside of quoted material. i really wanted to 
emphasize a bunch of stuff, but gave up after a while. C'est la vie.

In the HMI.glossary I developed a secondary practice of penning 
Monographs which further elucidate the Humanmarkup-specific 
definitions or uses beyond the dictionary-type definitions. I meant 
for the word Monograph to be regular and the actual text of the 
monograph to be italic simply to delineate it as being different in 
much the same way that a quote is.

In HM.frameworks and now in HM.applications, I am using a practice 
which will actually be useable in OO, UML and to a somewhat lesser 
extent, in xml by placing colons between terms that can be used as 
element, attribute or class names, without spaces before or after the 
colon to show a descending order relationship from general to 
specific. In HM.applications I am uploading as I go without changing 
the date each time I do so until it is done, as a way to be able to 
quickly check it on the web when i am not at home at the computers 
there. I will notify everyone when I have finished my pass at it, but 
if you want to look, please do,

That's the highlights. I try to be consistent, but I am human, too 
and prone to bugaboos, so I ask forgiveness aforethought.

Ciao,
Rex
-- 
Rex Brooks
GeoAddress: 1361-A Addison, Berkeley, CA, 94702 USA, Earth
W3Address: http://www.starbourne.com
Email: rexb@starbourne.com
Tel: 510-849-2309
Fax: By Request