[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
provide room for the reader to go "Wow! Note: the style
Heavy man...." guide does not
prohibit pathetic
pretensions on the
part of the author.
oo External links Who also reserves
the right to cover
At present external URLs are simply his butt with
entered as dead text. formulaic self-
deprecating humor.
Notes for the future:
External links will become live html links,
labeled in lower-case to set them off from
the usual internal doomfiles links.
Rather than go directly to the external
location, they'll do an internal html jump
into a special doomfiles "vestibule" page
(possibly called REFERENCES, or THE_OUT_DOOR).
This page will contain a listing of
live external links, with brief discussion/
description of what the links point to.
The purpose of the "Vestibule" approach
is a little hard to put in words, but It's something like this:
I've experimented with it in other web
pages (notably my San Francisco guide) Promiscuously linked
and I like the way it works. webs can be discon-
certingly fuzzy.
(In some respects, it's
better for *each page* Click-click-click
to have it's own vestibule, and you pass
but this would disrupt the rapidly through
doomfiles "browse sequence" multiple topics
too much.) and points-of-view.
With this
cluster of pages
you're supposed
to know you're
in once place,
listening to one
oo Regular doomfiles Links vs. NEXT Links voice.
Question: is it okay to have When you follow
a link redundant with the Next an external link,
or Prev link? if you need to
go through the
E.g. when the Next flows logically, "vestibule" on the
it also often seems logical to have way out, it
a duplicate, redundant floating link underlines the
next to a rectpara near the end. fact that you're
leaving, it
Answer: Yes, this is okay, because highlights
the browse sequence may be revised the boundary.
later, and then the floating link
might be necessary. Further, once
you're used to
But: when you *don't* expect that browse link it, it makes
to ever change, *then* the redundant floating possible a
link should probably be eliminated. different style
of reading, you
can defer
o Quotations following a
link because
oo Indicating quotations you know you
can find it
Doing quotations of large chunks of text is below in the
problematic, because the doomfiles format "vestibule",
essentially hides a "block quote": that sort which acts as a
of indentation is indistinguishable from "see also"
the placement of rectparas to indicate the section.
flow of thought.
And the
Putting double quotes around big quotes isn't a vestibule itself
great solution, but it's the only one that seems can be an
workable. interesting
page to read
Problems: through.
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).
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 - WELL-QUALIFIED]