Re: Editor recommendation

From	Don Y <this@isnotme.com>
Newsgroups	comp.arch.embedded
Subject	Re: Editor recommendation
Date	2013-09-01 17:02 -0700
Organization	Aioe.org NNTP Server
Message-ID	<l00kic$m5m$1@speranza.aioe.org> (permalink)
References	(3 earlier) <8761um66fz.fsf@digitalsignallabs.com> <kvrqlg$jd4$1@speranza.aioe.org> <kvsm5i.1qc.1@stefan.msgid.phost.de> <kvtcgs$i8c$1@speranza.aioe.org> <l007l3.13k.1@stefan.msgid.phost.de>

Show all headers | View raw

Hi Stefan,

On 9/1/2013 11:21 AM, Stefan Reuther wrote:
> Don Y wrote:
>> On 8/31/2013 3:05 AM, Stefan Reuther wrote:
>>> Don Y wrote:
>>>> On a *printed* (phototypeset) document, these things are really
>>>> easy to resolve.  On a *display*, they are much harder!
>>>>
>>>> E.g., I'm currently preparing a document on cubic Bezier curves.
>>>> I use a 10 pt serif typeface for body text.  This means footnote
>>>> text is 8 pt.  Footnote *references* (i.e., in the body text)
>>>> are superscripts -- so, about 5-6 pt on the 10 pt text.  Within
>>>> footnote text, subscripts are about 4-5 pt!
>>>
>>> Why on earth do you need to display all that in the final layout during
>>> document preparation?
>>
>> Because document preparation involves sorting out its visual
>> presentation!  If you don't care what the document looks like,
>> "compose" it in HTML and you'll never need to *know* how it will
>> appear on some particular browser!
>
> Sure I check how it looks like. But not at the same time I type it. Thus
> I can check whether each Bézier has its accent during editing, in a nice
> large screen font size. I trust my typesetting system to preserve the é
> even when the font size is reduced for a footnote.

You apparently tag *while* you are typing the original source.  So,
for example:
     <italic>Bezier<\italic>
or
     <Heading>Special Cases<\Heading>,
or
     See <xref (Heading) Special Cases<\xref>
I don't tag anything until layout.  My "input text" is just that:
straight ASCII text with no formatting information or special
characters.

A short code snippet looks no different from "body text" when I
import it.  I walk through each text flow tagging "special"
paragraphs with whatever tag is appropriate:

"Ah, this is obviously a <Heading>.  These five paragraphs are five
lines of <code>.  This wants to be a <footnote>.  etc.  I want to
insert a reference to this particular paragraph at this *other*
point in the text.  etc."

I rely on an "equation editor" to sort out how to express the
canonical representation of a cubic Bezier instead of *hoping*
that I can "manually" synthesize it as:

     <math>\begin{align}
     \mathbf{P}(t) = {} &\sum_{i=0}^n {n\choose i}(1 - t)^{n - 
i}t^i\mathbf{P}_i \\
     = {} &(1 - t)^n\mathbf{P}_0 + {n\choose 1}(1 - t)^{n - 
1}t\mathbf{P}_1 + \cdots \\
     {} &\cdots + {n\choose n - 1}(1 - t)t^{n - 1}\mathbf{P}_{n - 1} + 
t^n\mathbf{P}_n
     \end{align}</math>

and hope it ends up looking like I want it to look!  :>

[Sorry, in The Grand Scheme of Things, I don't rate that sort of
capability as a skill worth knowing!  :> ]

If I know I will be including several large code fragments or
tables, I will *plan* on importing them as separate flows so
they can be efficiently handled as separate entities.  E.g.,
anything more than ~10 lines of code warrants being set off
from the main body of text as a "figure" -- to help ensure it
stays together, visually, and doesn't get split up over different
pages (in much the same way that a table wants to be a cohesive
entity -- not just columns of text *within* the regular body
of text).

>> If your documents are *just* text, its a no-brainer:  let the text
>> break wherever it is convenient for the typesetter.
>>
>> But, when you add lots of tables, illustrations, equations, etc.
>> the process requires a lot more "eyes on" control.
>
> 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”)

Or, do you zoom around the entire document on "high magnification"
hoping you catch everything one "peep-hole" at a time?

>>>> "Cubic" in (1) is in italics as are "G1 Continuity" and "C1 Continuity".
>>>
>>> Semantic markup For The Win! You want to mark newly introduced terms?
>>>     \newcommand{\term}[1]{\emph{#1}}
>>>     ...
>>>     Thus, \term{C1 Continuity} implies \term{G1 Continuity}. However, the
>>>     reverse is not true.
>>
>> Again, it's not a question of markup language.  Rather, can you
>> discern that "C1 Continuity" is in the correct typeface *and* italic
>> while it is presented at that small *subscript* to the "footnote" text
>> size?
>
> 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.

I.e., "emphasis", "heading", "footnote", "code", etc. don't exist for
me *until* layout.  If I import a piece of code, it *is* a legitimate
".c" file -- not "source code adorned with layout/formatting info".

> I know people plan their university thesis with a work item
>     2 days: check that all headings have the same font, all
>     cross-references point to the right pages, etc.
> just before giving it to the printer. OK, this may be needed if all you
> have is Wordpad which has no stylesheets (or all you have is Word and
> you have never heard of stylesheets). I am not one of them.
>
>>>> "Special Cases" in (4) is bold.
>>>
>>> It's probably a reference somewhere? Let's make it a link.
>>>     For examples of these degenerate cases, see \ref{Special Cases}.
>>
>> Again, consider what a bold typeface looks like when rendered
>> that small.  You don't suddenly get more pels to work with for
>> that glyph!
>
> Again, why would I need that? I trust my system to set a boldface
> "Special Cases" if I tell it to.\

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?"

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?

*When* you correct it, how do you readily verify that you've
corrected it correctly?  E.g., in my original document, the
footnote:
     Unqualified, the term “Bézier”, herein, shall refer to cubic
     Bézier curves
did not contain quotes around the first Bezier reference.  They
were added while previewing the typeset version ("Crap!  I need
to quote that!").  And, I had to make sure I wasn't quoting
with the "wrong" quotation marks.
    Just zoom in (TO OVERCOME THE LIMITATIONS OF THE MONITOR) so
    you can see that you are typing '“' and '”' and NOT '"'.  Or,
    open the *source* document and type "\lq\lq" and "\rq\rq"

[I'd rather *see* the effects of what I'm typing *while* I'm
typing it -- instead of having to "refresh" the rendering
and remembering to double-check that (along with any other
changes I may have made)]

> In a preview with standard screen
> resolution, letters may become a little sludged, but looks like "Special
> Cases" even from afar, and if I really want to know, I can zoom in.

*I* can "zoom in" (and out!) too!  But, each time you do that,
takes time and effort.  And, takes time for you to "get your bearings".
Should I "zoom out" so I can see how any text I am inserting effects
the layout of other objects around it, on the page.  Then, zoom in
to verify that I have typed what I *think* I was typing?

>>>> Recall, footnote text is 8 point.  With a 150dpi display, this
>>>> corresponds to ~16 pels tall -- including interline leading!
>>>
>>> When working with the text, it's all the same size for me. Fixedsys
>>> Excelsior, 16 px (I believe).
>>
>> Because you don't produce photoready publications!
>>
>> Do you write everything in (la)TeX and then hand it to the printer
>> and say, "run off 10,000 copies"?  Or, do you run it through the
>> TeX executable and *preview* the result?
> [...]
>> And, how are you manipulating all of those illustrations, tables,
>> equations?  Just *hoping* they fall into convenient spots?
>
> Sure I preview. My point being: you don't have to see all details at
> once. When adjusting illustrations, I don't care about the precise
> content of the illustration; I care that there is an illustration, but
> don't need to see every pixel of it.

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!  :< ]

It also lets me change my mind as to how I want to reference
them without having to revisit Mathematica to "tweek" the
image I've asked it to generate.  For example, I originally
labeled the points A, C1, C2 and B (A and B being endpoints
while C1 & C2 were control points).  When I typeset the
equations for the curve, it was much easier to change this
to P0, P1, P2, P3 -- as the curve could be expressed as a
linear combination weighted Pi.  I could make that change
*within* the publishing program without requiring any changes to
the "image" onto which they were laid.

 From your descriptions and my *assumptions* as to how you work, I
gather you don't spend much time preparing these sorts of documents.
That it's more of an "accessory" activity for you.  Someone else
gives you a formal specification that you can just *read*.
Someone else prepares the final documentation for the user.
*Your* documentation can fit in comments in source files, etc.

I tend to produce about 4 pages of formal documentation for
each page of code:  a page of spec, a page of "documentation"
(explanations of the implementation, etc.), a page of test
strategy and a page of "user documentation".  Some subsystems
tip this balance one way or the other but it tends to
average out over the course of a project (hardware projects
have different sorts of documents but similar "effort weights")

[Of course, this lets me make my source code "more dense"
because I can move any lengthy descriptions, explanations,
derivations, etc. out of the commentary and *assume* anyone
reading the code already understands the requirements, theory
and structure laid out in those documents.  The source code is
then "just an implementation"  :> ]

So, I can spend 30 pages describing characteristics of cubic
Bezier curves that my code relies upon -- and, then never
have to explain *why* I am doing something *in* the code
that relies on those objects.

Of course, preparing such documents is a lot more "expensive"
than just adding commentary to some source.  But, the goal
of documentation is to ensure folks *understand* the issues
being presented -- not just a "check off" item that you can
claim you have satisfied.

[To that end, my introduction of multimedia and interactive
"demos" to the documentation will hopefully be a net asset.
Provide a richer means of presenting concepts instead of
just relying on lots of glyphs on paper...]

Thread

Editor recommendation Roberto Waltman <usenet@rwaltman.com> - 2013-08-28 16:18 -0400
  Re: Editor recommendation David Brown <david.brown@removethis.hesbynett.no> - 2013-08-28 22:46 +0200
    Re: Editor recommendation chris <meru@devnull.com> - 2013-08-28 22:10 +0000
      Re: Editor recommendation dp <dp@tgi-sci.com> - 2013-08-29 09:23 -0700
        Re: Editor recommendation Simon Clubley <clubley@remove_me.eisner.decus.org-Earth.UFP> - 2013-08-29 17:15 +0000
          Re: Editor recommendation dp <dp@tgi-sci.com> - 2013-08-29 10:38 -0700
            Re: Editor recommendation Simon Clubley <clubley@remove_me.eisner.decus.org-Earth.UFP> - 2013-08-29 17:49 +0000
              Re: Editor recommendation dp <dp@tgi-sci.com> - 2013-08-29 12:19 -0700
          Re: Editor recommendation Paul Rubin <no.email@nospam.invalid> - 2013-08-29 12:16 -0700
        Re: Editor recommendation Don Y <this@isnotme.com> - 2013-08-29 11:32 -0700
          Re: Editor recommendation Paul Rubin <no.email@nospam.invalid> - 2013-08-29 12:15 -0700
          Re: Editor recommendation dp <dp@tgi-sci.com> - 2013-08-29 14:04 -0700
            Re: Editor recommendation Don Y <this@isnotme.com> - 2013-08-29 14:25 -0700
              Re: Editor recommendation Robert Wessel <robertwessel2@yahoo.com> - 2013-08-29 17:05 -0500
                Re: Editor recommendation Don Y <this@isnotme.com> - 2013-08-29 16:32 -0700
              Re: Editor recommendation dp <dp@tgi-sci.com> - 2013-08-29 15:44 -0700
                Re: Editor recommendation Don Y <this@isnotme.com> - 2013-08-29 18:02 -0700
                Re: Editor recommendation Hans-Bernhard Bröker <HBBroeker@t-online.de> - 2013-08-30 13:22 +0200
                Re: Editor recommendation Don Y <this@isnotme.com> - 2013-08-30 15:00 -0700
                Re: Editor recommendation Hans-Bernhard Bröker <HBBroeker@t-online.de> - 2013-08-31 02:17 +0200
                Re: Editor recommendation Stefan Reuther <stefan.news@arcor.de> - 2013-08-31 11:36 +0200
          Re: Editor recommendation Randy Yates <yates@digitalsignallabs.com> - 2013-08-30 20:30 -0400
            Re: Editor recommendation Don Y <this@isnotme.com> - 2013-08-31 00:50 -0700
              Re: Editor recommendation Stefan Reuther <stefan.news@arcor.de> - 2013-08-31 11:54 +0200
                Re: Editor recommendation Randy Yates <yates@digitalsignallabs.com> - 2013-08-31 10:17 -0400
                Re: Editor recommendation Randy Yates <yates@digitalsignallabs.com> - 2013-08-31 10:20 -0400
        Re: Editor recommendation chris <meru@devnull.com> - 2013-08-30 13:29 +0000
          Re: Editor recommendation dp <dp@tgi-sci.com> - 2013-08-30 15:04 -0700
    Re: Editor recommendation George Neuner <gneuner2@comcast.net> - 2013-08-30 13:05 -0400
      Re: Editor recommendation chris <meru@devnull.com> - 2013-08-30 22:55 +0000
  Re: Editor recommendation Les Cargill <lcargill99@comcast.com> - 2013-08-28 21:22 -0500
    Re: Editor recommendation Don Y <this@isnotme.com> - 2013-08-28 19:54 -0700
      Re: Editor recommendation Les Cargill <lcargill99@comcast.com> - 2013-08-28 22:28 -0500
        Re: Editor recommendation Don Y <this@isnotme.com> - 2013-08-28 22:38 -0700
    Re: Editor recommendation George Neuner <gneuner2@comcast.net> - 2013-08-30 12:42 -0400
      Re: Editor recommendation Paul Urbanus <urb@urbonix.com> - 2013-09-02 21:20 -0500
        Re: Editor recommendation Paul Urbanus <urb@urbonix.com> - 2013-09-04 01:20 -0500
        Re: Editor recommendation Randy Yates <yates@digitalsignallabs.com> - 2013-09-04 07:22 -0400
  Re: Editor recommendation Don Y <this@isnotme.com> - 2013-08-28 19:52 -0700
  Re: Editor recommendation bbhack <bbhack@gmail.com> - 2013-08-28 22:41 -0500
    Re: Editor recommendation chris <meru@devnull.com> - 2013-08-29 12:19 +0000
      Re: Editor recommendation bbhack <bbhack@gmail.com> - 2013-08-31 11:54 -0500
        Re: Editor recommendation chris <meru@devnull.com> - 2013-09-03 15:32 +0000
  Re: Editor recommendation Tauno Voipio <tauno.voipio@notused.fi.invalid> - 2013-08-29 09:19 +0300
  Re: Editor recommendation Roberto Waltman <usenet@rwaltman.com> - 2013-08-29 10:01 -0400
    Re: Editor recommendation Tauno Voipio <tauno.voipio@notused.fi.invalid> - 2013-08-29 18:45 +0300
    Re: Editor recommendation Don Y <this@isnotme.com> - 2013-08-29 12:04 -0700
      Re: Editor recommendation Robert Wessel <robertwessel2@yahoo.com> - 2013-08-29 16:31 -0500
        Re: Editor recommendation Don Y <this@isnotme.com> - 2013-08-29 15:00 -0700
        Re: Editor recommendation Randy Yates <yates@digitalsignallabs.com> - 2013-08-30 20:50 -0400
      Re: Editor recommendation Randy Yates <yates@digitalsignallabs.com> - 2013-08-30 20:37 -0400
        Re: Editor recommendation Don Y <this@isnotme.com> - 2013-08-30 21:15 -0700
          Re: Editor recommendation Stefan Reuther <stefan.news@arcor.de> - 2013-08-31 12:05 +0200
            Re: Editor recommendation Don Y <this@isnotme.com> - 2013-08-31 11:26 -0700
              Re: Editor recommendation Stefan Reuther <stefan.news@arcor.de> - 2013-09-01 20:21 +0200
                Re: Editor recommendation Don Y <this@isnotme.com> - 2013-09-01 17:02 -0700
                Re: Editor recommendation Stefan Reuther <stefan.news@arcor.de> - 2013-09-02 19:55 +0200
                Re: Editor recommendation Don Y <this@isnotme.com> - 2013-09-02 16:22 -0700
                Re: Editor recommendation Randy Yates <yates@digitalsignallabs.com> - 2013-09-02 19:39 -0400
                Re: Editor recommendation Don Y <this@isnotme.com> - 2013-09-02 17:51 -0700
                Re: Editor recommendation Don Y <this@isnotme.com> - 2013-09-02 18:49 -0700
          Re: Editor recommendation Randy Yates <yates@digitalsignallabs.com> - 2013-08-31 15:13 -0400
            Re: Editor recommendation Don Y <this@isnotme.com> - 2013-08-31 13:45 -0700
  Re: Editor recommendation Habib Bouaziz-Viallet <h.bouazizviallet@free.fr> - 2013-08-29 16:31 +0200
    Re: Editor recommendation bbhack <bbhack@gmail.com> - 2013-08-31 12:03 -0500
      Re: Editor recommendation Randy Yates <yates@digitalsignallabs.com> - 2013-08-31 13:27 -0400
        Re: Editor recommendation bbhack <bbhack@gmail.com> - 2013-08-31 13:17 -0500
      Re: Editor recommendation Habib Bouaziz-Viallet <h.bouazizviallet@free.fr> - 2013-09-01 19:16 +0200
        Re: Editor recommendation Randy Yates <yates@digitalsignallabs.com> - 2013-09-01 19:52 -0400
          Re: Editor recommendation chris <meru@devnull.com> - 2013-09-03 14:41 +0000
  Re: Editor recommendation jhallen@TheWorld.com (Joseph H Allen) - 2013-08-29 20:09 +0000
  Re: Editor recommendation stephenXXX@mpeforth.com (Stephen Pelc) - 2013-09-04 12:10 +0000

csiph-web