Hi Stefan,
On 9/2/2013 10:55 AM, Stefan Reuther wrote:
> Don Y wrote:
>> You apparently tag *while* you are typing the original source. So,
>> for example:
>> <italic>Bezier<\italic>
>> or
>> <Heading>Special Cases<\Heading>,
>
> Sure, when I type a heading, I know *now* that this is going to be a
> heading, so I tag it *now* (instead of in a second pass, where I could
> overlook it).
Headings are always short/terse (because I don't like headings that
"wrap" onto a second line and I usually use a two column format...
not much room for a lengthy heading). So, "a few words" in a paragraph
by themselves is a visual cue when the text is imported.
I go through the document and click once *in* each such paragraph,
then click "Heading". The text is reformatted on that second click
to carry the attributes associated with a "Heading". At the same
time, I similarly tag any "Subheading"s that I come across. So,
by my first pass through a document, all of these "stand out", the
basic section numbering (autonumbered) is in place as well as any
page headers annotated (top of each page -- in the margin -- shows
the name of the first heading encountered on that page... an aid
to finding "sections" without having to visually scan the contents
of each page as you thumb through the document).
If there are other "special paragraphs" in the document (like "side
headings", "display quotations" or even short "code" fragments),
I will tag them as well. Basically, anything that has a special
"visual treatment" that you'd be able to recognize just from
coarse appearance (e.g., "display quotations" are usually set
off from surrounding text, indented and displayed in an italic
or script/decorative "font")
Because you only need to click twice to tag such a paragraph
(once *in* the paragraph to select it -- no need to highlight
all of it's contents! -- and once to pick the tag to apply),
You can go through ~100 pages in a minute or two (literally).
Then, I create a nominal "figure frame" (a first-class object into
which text/graphics/imagery/etc. can be imported). I try to keep
most "figures" to be a consistent size -- not too small and not too
large (though there are always exceptions). Within this figure
frame, I introduce a second frame containing the caption text
"Figure <some identifier>: <some caption>". I then insert this
composite "captioned figure frame" at specific points in the body
of the text.
By convention, this is almost always immediately after a sentence
similar to "Figure X illustrates the relationship between foo and
bar." This ensures the actual frame will be inserted *after* the
text that is referencing it -- even if that forces it onto the
next physical page.
This sentence will be in a paragraph that is immediately above a
terse (in the same way that the Headings and Subheadings were terse)
paragraph beginning with "FIGURE" (my convention: "insert a figure,
here"). The text following the word "FIGURE" will be the caption for
the particular "Figure" that will be contained in this newly inserted
"figure frame". So, I cut and paste it into that "caption frame".
The act of inserting the captioned frame has created a unique (serial)
identifier for that figure. And, the "Figure X" body text referencing
it can be replaced with a "cross reference" tag so the referencing
text (immediately!) reflects the actual identifier for that figure.
This also makes the automatic creation of the "List of Figures" a
piece of cake! (ditto for Tables, as below)
In some cases, a figure may be nothing more than a "chunk" of text
that I want to treat as a solid entity. E.g., the code for a
function -- which might want to be typeset as a single wide column
instead of a pair of narrower columns).
Once all the figure frames have been inserted, I go back and paste
the images, illustrations, graphs, etc. for each of them into their
respective frames (these are each freestanding files, typically,
so this just embeds a reference to the "image" in the frame -- but,
the contents of the file appear on screen in that frame so I can
verify that I have selected the correct file, scale it to fit the
frame, etc.
Tables are a bit more complicated as they often have different
forms -- number of columns, rows, heading rows, ruling between
columns, etc. And, some really large tables might want to be set
in their own frames (just like the figures). I have several documents
that have tables that span 5 or 6 pages! Obviously, I want to be able
to manipulate these as objects and not let the program decide where
they should reside and how text should flow around them!
After this, I build any equations that have to be inserted. If these
are simple (e.g., polynomials, rationals, etc.) they are almost like
typing in regular text (though the range of symbols used and how they
are typeset requires special handling).
OTOH, if they involve more complex "decorations", delimiters (different
levels of parens/braces/etc), varying height elements (integration,
summation, product, matrices, etc.) then it can be pretty tedious
to get things right. Esp if it is a series of equations showing
how something was derived.
Once the equations, tables and figures are in place, I can see how
the layout has been mangled to accommodate their individual space
requirements. Given the large frequency of these in my documents,
it is hard for most automated tools to come up with an efficient
layout that doesn't inject lots of "wasted whitespace":
"Gee, I wasn't able to fit this figure in that 3.4 column inches
at the bottom of page X -- cuz it's frame is 3.5 inches tall. So,
I've left a big empty space, there, and moved this to the top of
page X+1. Ah, but that caused the table that had previously fit
at the bottom of page X+1 to be split such that half resides on
X+1 while the other half nor resides on X+2 (But, don't worry, I
took the liberty of modifying the caption for that table to
append "(Continued)" to it *and* also made sure I replicated the
heading rows(s) for the table onto that second fragment)"
As a result, I typically have to do a lot of tweeking to make things
more visually pleasing -- adjust the sizes of image frames, elide
a word/phrase from a paragraph to eliminate a widow/orphan, add some
embelishment to the text to make a "big hole" less empty, etc.
But, you have to resist doing this prematurely as the document often
has *semantic* changes required. So, I read through it, carefully,
and verify that the issues I present are clear. Often this means
adding a footnote to some body text (or, caption text or even
text *within* cells of a table!) This further alters the layout
of the document. Sometimes, adding a single word to a footnote
has dramatic consequences to how the rest of the document lays
on the page -- because that word caused a footnote to wrap onto a
second line (even at 8 points, a line is a line!) which caused
something else to fall out of that column, page, etc.
It's during this first reading where I tag *words* and *characters*
(previously, I've only tagged *paragraphs*!). "Character tags" are
a disjoint set from "paragraph tags". So, I can have a "Code"
character tag that I apply to individual words or characters *within*
a paragraph along with a "Code" paragraph tag (which, conveniently,
visually resembles the "Code" character tag) that applies to paragraphs.
So, in body text like:
"The alt statement is used to multiplex sources from the different
channels which can source events -- the data stream and the timeout
channel."
I can select "alt" and apply the "keyword" tag -- which is a special
form of the "code" tag (e.g., fixed width "courier", emboldened).
This is where I search & replace "etc.", "et al.", "i.e.", "e.g."
etc. with "<foreign language><whatever><\foreign language>" (which
visually renders them in italics versions of whatever font they
are currently typeset as -- but, semantically tags them as
"foreign words").
Similarly, words/phrases that seem to require "emphasis" as I am
reading the text get tagged with the "Emphasis" character tag.
These also appear in italics -- but, there are different semantics
involved (from "foreign language" or "article title" or any other
character tags that *happen* to appear as some form of italics).
Being able to make these changes *interactively* and see the (visual
and layout) consequences immediately helps guide any further changes
that I make. ("Hmmm, if I apply that tag universally, then all of
this text is going to stretch a wee bit and I'll end up filling
up this void *without* having to resort to fine kerning changes...")
As I said, the presence of these large typographical objects makes
my documents tedious to typeset effectively ("in a visually pleasing
manner").
>>> Sure. But I don't need to see all the subscripts and accents in the
>>> formula at the same time as the headlines. To see the subscripts, I can
>>> zoom in. To see the headlines, I can zoom out. Then I see an
>>> indecipherable blob that looks like a formula. Fine, there's the
>>> formula, here's the text that flows around it, done.
>>
>> So, how are you *proofing* the result? *Hoping* you got it right
>> when you were typing all that ASCII text *prior* to importing
>> it to your WYSIWYG previewer? *Hoping* you remembered to use
>> "open double quote" and "close double quote" to bracket
>> �B�zier� instead of straight double quotes ("B�zier") or,
>> worse, half-and-half (�B�zier" or "B�zier�)
>
> They look different even in normal font sizes. And to know for sure,
> there's a search function to search for things like straight quotes, or
> closing-quotes-not-followed-by-a-space.
You (at least, *I*!) don't want to have to think of every possible
thing you might have to verify and, thus, invoke a search function
to locate. It is *so* much easier just to run your *eyes* over
the resulting page and notice, "Gee, that should be straight
quotes instead of curly quotes" or "Yes, those quotation marks
*should* be immediately followed by a period as they enclose
the last word in that sentence".
>> Or, do you zoom around the entire document on "high magnification"
>> hoping you catch everything one "peep-hole" at a time?
>
> If it need be, sure. Normal-size text can be read at normal
> magnification, on page per screen. Formulas with small subscripts need zoom.
I don't take out a magnifying glass when I am reading a *printed*
version of the document. Why should I have to use one when I am
*typesetting* it? :>
>>> Again, I trust my typesetting system that if I set something in italic,
>>> it will also be in italic when moved to a footnote.
>>
>> So, you are doing all your tagging *before* seeing it typeset.
>> <emphasis>Oh My!<\emphasis> instead of benefiting from a GUI
>> to apply tags as needed.
>
> Yes. (And the problem with usual GUIs is that they can only display
> "italic", and cannot distinguish between "loanword", "new term", "name
> of a person", "name of a publication", or other reasons why one could
> want a word in italic. Semantic tagging during input also allows to make
> things like "I don't want this highlighted, but I want it in the index".)
Ah, get better tools! :> I can inspect the tags (both character and
paragraph -- cuz both can be in effect at a given point) that are "in
play" at any point in the text (location of cursor) by looking at the
status line as I move the cursor along. I can see where each
"reference point" in the text occurs (without affecting the actual
spacing or layout of the surrounding text).
E.g., an index entry tagged to a particular point in the text; a
particular figure frame's "insertion point" (which, on inspection, is
a reference to the actual *frame* located elsewhere and containing that
frame specific "marker"); the *text* (fetched *from* another document)
associated with a reference to a paragraph in that other *document*
(See section 23, "Output Characteristics" in the "System Hardware
Reference" document); etc. And, all of them in terms that a "mere
human" can relate to (no "\xref(ref "SysHard.doc", foo)" notation).
>> What's your obsession with "trusting your typesetting system"?
>> I trust mine as well! Difference is, you apparently choose to
>> type in all those tags *before* the "input" has been typeset.
>> And, you're thrilled that this isn't corrupted as it is rendered
>> "typographically".
>>
>> Mine isn't either! I just don't spend time typing "\vfill\eject"
>> when I want to insert a page break. Or, "\line{\hfil Flush right}"
>> to cram something against the right margin ("padded left").
>>
>> I.e., you can read the *content* of one of my documents "as a
>> normal human being" before it is imported. No concern over
>> "Gee, what does '\hrule' mean?"
>
> "Before it is imported". So the difference might be that you write
> something, and then import it somewhere else. I prefer directly writing
> for the target system.
When you write your code, do you embed the typesetting commands
*in* your source? (e.g., LP) Or, do you *add* those AFTER you
have imported it into your documentation?
> "Write and import somewhere else" is what I use if someone wants me to
> use Word to print C code, or something like that. I write the C code in
> Emacs and import it into Word :)
*And*, add the tags *in* word!
When I publish source in a document, the source remains UNCHANGED!
No bugs creep in because I accidentally mangled the source while
trying to INJECT typesetting directives.
I despise documentation that contains technical typos. E.g., I
should be able to literally type any code, schematics, etc. that
is contained in your documentation and EXPECT IT TO WORK as you
have described it to work (in that documentation). I shouldn't
have to "debug" your typesetting.
"Hi, I've reproduced EXACTLY what your XYZ-123 document sets forth
on page 84 and it's not working. I've looked at it and can't
imagine why its not working. What have I done wrong?"
("Ah, sorry. Not *your* fault! The compiler switches listed
there are in error. That should be "-g" not "-G"!")
> But even when I write something not in the target markup format, I try
> to tag it a little. That's one area where XML transformations come in
> handy, for example. Or little one-screen Perl scripts.
>
>> If you find something that needs to be corrected while proofing
>> the *typeset* rendering of the document, do you correct it
>> *in* that WYSIWYG? Or, do you have to re-open the "source"
>> document, locate the corresponding portion that contains the
>> text/tag/formatting that you want to alter, tweek that, flush
>> it to disk and then "refresh" the WYSIWYG rendering?
>
> Precisely.
>
> And, being used to programming, I find this workflow very natural.
I don't. It means I have to maintain *two* documents concurrently
(even if one is just a "memory buffer"). I make my changes to
the underlying "source" *through* the viewport that the GUI provides
me. So, I know that what I am seeing is actually what I *have*
(have I saved the source file and not yet updated the GUI? Have
I saved the GUI but made changes directly to the source file which
have not yet been saved and *refreshed* in the GUI? Too prone to
error when you think you're "done" with one -- only to discover
that the *other* is "more recent")
> It's not a good workflow for things like party invitation posters. But
> for tech manuals I find it optimal.
So, you ensure any graphics imagery you may have been editing is flushed
to disk, then refreshed in the GUI; ditto any schematics; source code;
etc.? I guiess I'm just old and senile -- I could never be sure I
had flushed *everything*, refreshed *and* REVIEWED the typeset version
of the composite document before closing down a work session each
day. I'm *sure* I would OFTEN find the document wasn't "as I
remembered it" the next morning ("Gee, I thought I had changed that
paragraph, yesterday?" or, "Funny, I don't *remember* that text as
not fitting in its frame when I looked at it yesterday...")
>> How do you add callouts to your illustrations? To as great an
>> extent as is possible, I *don't* include text in "images" that I
>> import (hard to do with schematic fragments!)
>>
>> E.g., all of my Bezier curve examples are created in Mathematica
>> and imported without any text annotating the points, coordinates,
>> axis, etc. Instead, these are pasted on as callouts *after*
>> the image has been imported. This allows me to ensure that
>> the designations for each point appear in the same "font" and
>> representation that they are referenced as in the body text.
>>
>> [One problem has been getting Mathematica to use the same
>> "colors" that the publishing program uses! :< ]
>
> Works fine with LaTeX and TikZ (or xfig).
>
> (But, yes, it needs getting used to. And, admittedly, I don't use many
> pictures, and for UML diagrams exported from a modeling tool, or plots
> exported from, say, Excel, I don't care for fonts. After all, it's tech
> docs, not a glossy magazine.)
I find documentation that is easy on the eyes tends to get more use
than stuff typeset with a lineprinter (Gries' _Compiler Construction
for Digital Computers_ being a great example of the latter!).
Screenshots that are too big, small or *coarse* are tedious to
look at. B&W photos (esp if reproduced xerographically!) obfuscate
instead of enlighten. Typos, inconsistencies, inaccuracies, etc.
confuse instead of enlighten.
[Of course, "novices" who go hog-wild with "fonts" and "frills"
and colors work against those goals!
Documents are supposed to convey information. Good documents
convey it accurately and effectively. E.g., I can "show" a
"reader" the consequences of a particular formant synthesis with
*sound* much easier than I could explain the characteristics of
those sounds "in text" -- to all but a veteran speech pathologist!
And, *much* easier than trying to describe that in the abbreviated
format of "source code commentary"!
"Ah, so *that's* why we have all this bizarre math happening on
lines 93 through 167! Omit it and you lose this characteristic!"