[PREV - BROWSE_SEQUENCE] [TOP]
STYLISH_HAND
January 22, 2005
Rev: February 14, 2007
The doomfiles handbook of style...
(yes, just what the world has been waiting for)
o Date Format
Each page should (at a minimum) have a date
in the upper right reflecting the date the If a date field is missing
material was written. entirely, that usually means
it was written before I
The format of that day is realized I needed them, in
the mid-to-late '80s.
MonthName DD, YYYY
For example: January 22, 2005
Don't use leading zeroes on one digit days.
For major revisions and re-writes, Try to add
additional dates under the main one:
Rev: March 3, 1999
Don't be too fanatic about adding these dates
(more than 3 or so gets very unwieldy).
The month-name fields should be
padded with spaces so that they're
all of the same width, and if
necessary, a leading space should be
added to the day -- the goal is to An example:
get the years lined up in the same
column: as time goes on it's more March 3, 1998
useful to be able to compare years. Rev: February 14, 2007
(Months and days are unlikely to
matter, until someone gets to work
on my biography). Why would you
put spaces before
The month and day are already overkill, the day and not
so whatever you do don't add a full before the year?
time-stamp (just because a computer
makes it easy to do something doesn't Answer: to make sure
mean it's a good idea). the year isn't confused
with a doomfiles link
by the software I
process this stuff
o Extended Characters with. Two spaces
create a boundary,
Seven bit ASCII was historically the and numerics (along
original format for the doomfile, and with capitals) are
it remains the preferred form. allowed in node names.
Where international characters are
really needed they should be
entered as "ampersand code" The Martin Ramisch
html entities, e.g. "é" page is probably
for an e with an acute accent. still the preferred
reference.
But weirdly enough, I
think "lynx" has some
trouble with these.
Need to investigate
this issue (are
numbered entities
more portable?).
o Eighty column limit
Doomfiles formating presumes 80 columns
of fixed width text -- this is partially
for historical reasons (in it's earliest
form it was viewed on VT-100 terminals), HISTORY
and partially a decision made early in
the web era to always be "lynx friendly".
Notes for the future: we're past the
stage where there's likely to be many And it's always
readers limited to 80 columns, but I possible that
have no immediate plans to change this smaller screens
policy. will make a comeback
with portable
equipment.
o Book Titles
Book Titles have always represented a challenge for
7-bit ascii: in print they're supposed to be italicized,
so should one use the bracketing asterix notation?
Perhaps one of these:
*War and Peace*
*War* and *Peace*
*War* *and* *Peace*
I submit that this looks *even* stupider than using
them for indicating inflection like *this*.
The old typewriter manuscript convention was to
use underlines to indicate italics, so perhaps
bracketing underscores can be used to suggest this?
_War and Peace_
That's not too bad, but using that form inside a
sentence, e.g. _War and Peace_, with other
surrounding punctuation, is just a little too messy
and visually confusing.
Conclusion: drop the distinction between short pieces
and long works, and just use double quotes on the title
just as though it were a short-story:
"War and Peace"
Exception:
When it seems more convenient (e.g. single word
book titles) you can just use the capitalized title
without any form of bracketing: Dhalgren.
Note for the future: I will consider using
actual italics via html mark-up:
<I>War and Peace</I>
o Acronyms
Inventing new acronyms is prohibited, and using
existing acronyms is to be avoided, depending
on how familiar they seem; one should err
on the side of presenting an inane expansion
rather than confusing, e.g.
AI ("Artificial Intelligence") is unlikely to ...
The difficulty with acronyms is that while they
can save typing and effort on the writer's part,
they can slow down the reader. The excuse "but
they can figure it out" is the cop-out of a lazy
writer.
As an alternative to acronyms, look for other
abbreviated forms. e.g. in a long title one
might use a prominent, unique word.
For example, Heinlein fans sometimes resort to
initials to refer to his more verbosely titled
works:
"Of course tmiahm is much better than siasl"
Someone familiar with Heinlein's works can no doubt
puzzle over that and expand it to "The Moon is a Harsh
Mistress" and "Stranger in a Strange Land", but it
takes much less thought to expand this form:
"Of course Mistress is much better than Stranger"
o Rectpara formatting rules:
Note the jargon: the doomfiles uses small
floating roughly rectangular chunks of text, More jargon:
which I've always called "rectparas". What is one
particular
"Rectparas" tend to be shorter than traditional entry in the
paragraphs, often just a single sentence (sometimes doomfiles
more, though). A paragraph of prose tends to map called?
to a chain of rectparas, so the rectpara might be Traditionally,
thought of as a grouping somewhere between the I've called it
sentence and the paragraph. a "node".
Everyone else
thinks they're
In order to facilitate programmatic "pages", though.
handling of rectparas, they should
always be bounded by at least two Policy:
blank columns on the left and right The left call it a
sides (as well as at least one blank border "page", but
line on top and bottom). of the remember
window it's a node:
The aspect ratio of rectparas can be counts a confluence
adjusted at will to improve the layout... also, of of lines of
if there are many chains of discourse course. thought in
in play, then the rectparas will tend a network
to be narrow. of thoughts.
When there's no external pressure on ("Knot"
the width of the rectparas, the rule would be
is to try to pick a width that Expanding much a better
allows for a smoother right margin beyond half metaphor
(i.e, a more rectangular appearance). the screen than "page")
(40 columns)
isn't recommended:
Allow some margins
to easily insert
comments like this
one.
o Formatting chains of rectparas
A single flow of thought should be
arranged in a straight line, a change
of direction indicating a shift in
thought.
[]
[]
[]
{}
{}
[]
[]
[] {}{}
<>
<>
Usually, the flow should go
left-to-right or top-to-bottom, For obvious
or some combination of the two: reasons.
----> But should be
|\ used sparingly.
| \ Well, they're
| \ allowed...
V _| Chains
that
move
differently
oo Avoid accidental alignment of horizontal boundaries
This is a subtle one: if the top or bottom of
two adjacent rectparas happens to coincide, the
eye tends to assume there's some meaning in that
horizontal connection.
So with two parallel chains running,
rectaparas may need to be reformated to
keep horizontal boundaries from
accidentally lining up with each other.
Poor:
Subject 1: Subject2:
babbling
Babbling babble yammering.
babble. yammer, yammer.
<--\
Babble, babble, bab. Yammer, Yammer, accidental
Babble, babble. yammer, yammer... alignments
<--/
Babble, babble, bab- Yam!
ble, seventine,
babble.
Better:
Subject 1: Subject2:
babbling
Babbling babble
babble. yammering.
yammer, <--\
Babble, babble, yammer. | horizontal
bab. Babble, <--/ breaks are
babble. Yammer, Yammer, now staggered
yammer, yammer... <--\
Babble, babble, <--/
babble, Yam!
seventine,
babble.
In general, skinnier rectparas
make accidental boundary
alignment less likely.
o Link policy
oo Where Possible, Use Maybe I should codify
Placement to Indicate Flow the use of "o" bullets,
too? But let's not
As with chains of rectparas, the go hog-wild.
placement of a link should indicate
something about what kind of link (Yee-hah, I'm style
it is. guide crazy)
If it's a continuation of the
current thought, the link
should be lined up with the
current rectpara.
SCAFFOLDING
If the link is more of
an oblique association
then it should probably
be placed off to the side. ATOMIC_THOUGHT
In practice, however, there's usually not
enough freedom of placement to follow this
rule rigorously: links must be placed
anywhere they fit that has some proximity
to the appropriate text.
oo Indicating The Strength of a NEXT Link
A *weak* connect NEXT link should have
some additional blank lines to set it off.
A tighter connection should
have no such gap at the
bottom of the page.
One exception to this, padding the bottom
with blank lines can be used to emphasize
the final remark. If I've succeeded in
ending on a bang, on some quasi-profound
thought, the whitespace is supposed to Note: the style guide
provide room for the reader to go "Wow! does not prohibit
Heavy man...." pathetic pretensions on
the part of the author.
Who also reserves the
right to cover his butt
oo External links with formulaic self-
deprecating humor.
It used to be I would simply enter
external URLS as dead text, but of late
I've been inclined to make them live
links with a standard label of "[ref]"
(though soon I'm going to switch that
to the more comprehensible "[link]").
Notably, the label is in lower-case
to set them off from the usual And to tell you the truth, I'm
internal doomfiles links. not *sure* why I use the same
label on all of them... but then
in the doomfiles the surrounding
text always describes them so
a more informative label would be
redundant and not add very much.
I've abandoned my old "vestibule"
idea (though it might be partially
resurrected later).
WEB_VESTIBULE
oo Regular doomfiles Links vs. NEXT Links
Question: is it okay to have
a link redundant with the Next
or Prev link?
E.g. when the Next flows logically,
if the "content" also includes links
to relevant pages, then there's often
going to be some duplication...
E.g. the reader is presented with a link
near the bottom to the TEETH_AND_DOXES page,
but *right* at the bottom is the standard
"next" link labeled "NEXT - TEETH_AND_DOXES".
This redundancy can seem silly. Should
it be eliminated, or is it okay?
Answer: Yes, this is okay, because
the browse sequence may be revised
later, and then the link embedded
in the text might be necessary.
*Hypothetically*, if you *knew*
that the browse sequence was fixed
and the next was never going to change,
then eliminating the redundancy would
be an improvement.
In practice I know that can't be counted on.
It's a continual struggle for me to find ways
to tell future versions of myself to leave
some things alone-- there always seems to be
a reason to mess with things.
o Quotations
oo Indicating quotations
Doing quotations of large chunks of text is
problematic, because the doomfiles format
essentially hides a "block quote": that sort
of indentation is indistinguishable from
the placement of rectparas to indicate the
flow of thought.
Putting double quotes around big quotes isn't a
great solution, but it's the only one that seems
workable.
Problems:
o The additional double-quotes can be a little ugly
(visually noisy).
o You have to watch for embedded quotes within the
quote, and change them to singles (and any
singles embedded in those embedded quotes into
doubles, etc.).
o In multiple paragraph quotes, the standard is
to leave off the trailing quotes on the
preceding paragraphs. I've always hated this: A simple solution:
Messy, inconsistent, feels unbalanced, makes just ignore this
it harder to see that the preceding para is a rule, and always
quote. use closing quotes
at the end of the
But whenever I try an alternate approach, paragraph, even
I change my mind about it later, and if you're going
go back to putting in the double-quotes. quote another
para in sequence.
oo Attributions I'm trying that
on a trial
For very short block quotes, the attribution basis: Sept, 2007.
can follow it, but for *long* ones, the
attribution should usually precede it, to help
emphasize that the following is a quotation...
and to resolve a dangling issue quickly that
the reader must be wondering about.
(It's an issue of "end weight".) Note that in usenet
quotation style,
The usual policy, then: the attribution
precedes the quoted
Lead every quotation with an text.
introductory rectpara (that
closes with a colon), to make
it clear that the following
rectpara is a quote.
You then close off the chain
of quotations with the
specific details of the
reference (page number, etc).
Chains of blockquoted paragraphs
should be arranged vertically, (You might think that this
with no change in direction. style could substitute for
using double-quotes to
indicate a block quote, but
there's still a problem
with comments *next* to the
quotation: it's visually
ambiguous whether it's a
different quote from the
same source).
I've noticed an odd ambiguity
lately that can arise if I'm
trying to do some sort of
comic voice, an intepretation
of what a certain kind of person
might say. Normally I offset
those with double-quotes, but Possible solution:
if I'm intermixing remarks like start using html
that with actual quotations, it italics for the
can look like "putting words in "comic voice", at
someone's mouth". least when there's
a possible ambiguity.
todo: CALLING_COLLINI
o Browse sequence (i.e. the NEXT and PREV links):
In choosing places for pages in the browse
sequence, it's better to try to get at a
deeper understanding of what the material
is about, even if the association is a
little obscure and likely to confuse some
readers.
For example, a string of a half dozen nodes
all about a particular writer will no doubt
look like a series of tight connections to
the reader, but really many different
disjunct issues could be under discussion
there.
It's better to put Tolstoy quotes on
different subjects in the context of a
discussion of those subjects, rather than
in a discussion of Tolstoy.
Similarly, a handful of nodes that look
like they're about "punk rock" might
actually be about multiple different
subjects:
alternative esthetics,
the evolution of scenes,
political tribalism,
etc.
A "NEXT" link may be puzzling without being weak.
o handling variant spellings
I've been gradually shifting to
"evidently" over "evidentally" I could use that to justify
because it's shorter and more dropping the British "u"s
common. in things like "color/colour",
but really the reason I do
Similarly, with: that is we Merkin Imperialists
"subtle" and "subtile" conquered the "English" language
long ago.
Possibly: come up with
a list of deprecated
spellings, and grep
for them now and then.
o An issue with emdashes:
Visually, I prefer emdashes (Jun 15, 2009)
to be double hyphens bracketed
by spaces -- just like that one
there.
But the standard text formatting
in emacs likes to break on spaces
-- just like that there, where the
emdash has been moved to the front.
I don't ever want that to happen.
A simple, provisional fix, is to
elide the leading spaces-- that, then
would be an emdash, which I suppose
some people might prefer. It might
even grow on me.
Perhaps The Right Thing would be
for me to modify the formatting
software, using a different engine
for doomfiles rectparas.
Alternately, I might type in html
non-break space codes in places I
don't want it to break:
Alternately, I could get in the habit
of typing &emdash; (or whatever it is)
to create html emdashes manually, or I
could change my processing code to insert
those automatically: this would mess with
my formatting though (I need fixed width
text at present).
And I would like to get away from any sort
of special intervention for these cases
though: rather than a need to fix breakage,
I'm going to change my style so it will
stop interacting badly with the emacs
default behavior-- elided spaces before
the dash is now the rule.
I stop short (for the present) with automatically
modifying existing cases to comply with the
new rule.
o Images Thu May 3 10:43:24 2012
No images
So obvious I forgot to mention it!
The original df format was an ascii-only medium.
When I carried it over to the web, I decided to
stay lynx-friendly...
This business looks increasingly silly.
Some points are easier to get across with
diagrams (not to mention equations).
I'm now considering adding
diagrams to BRENNER_6 by
linking to photos in another
section of my webpages.
Why not just put photos in
the doomfiles?
For that matter, I've long since gotten
over my aversion to silly frills like
"syntax-coloring". Why not use colors
to convey information, e.g. in diagrams?
Keeping it simple may usually be a virtue,
but sometimes a "new" technology can
be a simplification.
--------
[NEXT - WEB_VESTIBULE]