[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: &nbsp;

  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]