Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > comp.arch.embedded > #13216 > unrolled thread

Editor recommendation

Back to article view | Back to comp.arch.embedded

Contents

  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

Page 3 of 4 — ← Prev page 1 2 [3] 4  Next page →

#13230

On 08/29/13 03:41, bbhack wrote:

>
> Try Netbeans.
>
> https://netbeans.org/

Wasn't that originally a Sun Micro product ?. Anyway, the fact that
it's available for Solaris Sparc and X86 means i'll be having a look
at that. Thanks for the pointer...

Chris

>

[toc] | [prev] | [next] | [standalone]

#13277

On 08/29/2013 07:19 AM, chris wrote:
> On 08/29/13 03:41, bbhack wrote:
>
>>
>> Try Netbeans.
>>
>> https://netbeans.org/
>
> Wasn't that originally a Sun Micro product ?. Anyway, the fact that
> it's available for Solaris Sparc and X86 means i'll be having a look
> at that. Thanks for the pointer...
>
> Chris
>
>>

Yes, it originated at Sun. It's written in Java, but don't let that 
scare you off. Other that the fact that it takes about 20 seconds to 
start up, it works well. If it did not have Emacs keys available, I 
probably would not use it.

[toc] | [prev] | [next] | [standalone]

#13304

On 08/31/13 16:54, bbhack wrote:

>
> Yes, it originated at Sun. It's written in Java, but don't let that
> scare you off. Other that the fact that it takes about 20 seconds to
> start up, it works well. If it did not have Emacs keys available, I
> probably would not use it.
>
>

Downloaded the windows C/C++ version for a quick look. 95 Mbyte download 
and
~200Mb install, according to the install program. Took about 18s for the
initial load but everything instant once it is loaded. Like most things
Sun, target can be localhost or a network address. The default debugger
is gdb, which suggests that it may work with openocd and makes it very
interesting indeed. Gui has a nice lightweight feel about it, which is more
than can be said for some of the other offerings.

Oh yes, and over 700 plugins available !!!...

Chris

[toc] | [prev] | [next] | [standalone]

#13227

On 28.8.13 11:18 , Roberto Waltman wrote:
>
> What editor would you recommend for code development?
> Looking for something that understands C & C++ syntax, can define
> projects, run external compilations, etc. and has active support.
> My choice would be CodeWrite, (if it was still supported.)
> For some reason never got used to Emacs, and Eclipse is too ginormous
> for my taste.
>
> Alternatives?
>
> Thanks,
> --
> Roberto Waltman
>
> [ Please reply to the group,
>    return address is invalid ]


I had the same feeling toward Eclipse, as it felt a monster when running 
on the computers of yesterday. Now, the CPU speeds and memory capacities 
are much better, and you can tune Eclipse to your heart's content.

I have run Eclipse on Mac OS X, Linux (several flavors) and Windows, and 
I'm pretty happy with the results. However, there is a hefty learning 
step to climb until one feels at home with the myriad of settings.

My old favorites were WordStar, nedit, Codewright, Smultron and kate, 
but they have all given way to Eclipse with CDT plug-in. With quite 
modern hardware (MacBook Pro of 2008), it runs well even in a virtual 
machine with Linux or Windows XP (no idea of newer windozes, however).

The CDT nag-machine is much more than bare syntax coloring, it quite 
well replaces lint, as well.

-- 

Tauno Voipio

[toc] | [prev] | [next] | [standalone]

#13231

>What editor would you recommend for code development?
 
Thanks for the replies - my notes in no particular order.

I knew about all the options except Smultron (not a Mac guy,) and  the
new implementation of Brief, and thought CodeWright was dead.
Pity the new Brief doesn't have the original's macro language. (I used
it extensively in the DOS days. )

By "still supported", I meant "bugs are fixed"

No CVS integration needed.

Working under windows when at work.

I don't want my spaces replace by tabs either  ;)

I used Nedit and recommended it to others, but did not use it under
Windows

Will give a try to Eclipse again, although don't like the screen real
state it uses in things other than the files edited.
Specially when I need to use larger and larger fonts as time goes by.
(Not everybody has dual 30" monitors.) And what was that Saturn-like
icon for?
--
Roberto Waltman

[ Please reply to the group,
  return address is invalid ]

[toc] | [prev] | [next] | [standalone]

#13234

On 29.8.13 5:01 , Roberto Waltman wrote:
>> What editor would you recommend for code development?
>
> Thanks for the replies - my notes in no particular order.
>
> I knew about all the options except Smultron (not a Mac guy,) and  the
> new implementation of Brief, and thought CodeWright was dead.
> Pity the new Brief doesn't have the original's macro language. (I used
> it extensively in the DOS days. )
>
> By "still supported", I meant "bugs are fixed"
>
> No CVS integration needed.
>
> Working under windows when at work.
>
> I don't want my spaces replace by tabs either  ;)
>
> I used Nedit and recommended it to others, but did not use it under
> Windows
>
> Will give a try to Eclipse again, although don't like the screen real
> state it uses in things other than the files edited.
> Specially when I need to use larger and larger fonts as time goes by.
> (Not everybody has dual 30" monitors.) And what was that Saturn-like
> icon for?
> --
> Roberto Waltman
>
> [ Please reply to the group,
>    return address is invalid ]


Did you notice that there is a box-like icon in the right top corner of 
the editor frames (and quite many others)? It can be used to maximize 
the window. There may be several files open in the same window, and they 
may be used as split screen. I'm usually using the editor window 
maximized with two tabbed subwindows containing the files currently of 
interest. This has been sufficient for me (67 yrs) on a MacBook, though 
I like the 24 inch Cinema display on BigMac more.

Please take the time to wade the workbench and CDT documents. A single 
pass was not enough for me, but after some frustrating 'Where on Earth 
is the function I'd find' the terrain starts to feel more familiar.

The globe in Eclipse icon is a darkened Sun in an ... eclipse.

-- 

-Tauno

[toc] | [prev] | [next] | [standalone]

#13243

Hi Roberto,

On 8/29/2013 7:01 AM, Roberto Waltman wrote:
> Pity the new Brief doesn't have the original's macro language. (I used
> it extensively in the DOS days. )

I found the ease of creating a "keystroke macro" to be the most useful
tool!

Typically, I would create two windows into the same file (most often
one above the other -- but depends on the actual nature of the task
I was trying to perform).

The top window would usually be what I considered the "source" window
and the bottom, the "destination".

I would *carefully* position the cursors in each window where I wanted
them to be -- "initial source" and "initial destination".  Then, in the
source window, "begin" the keystroke macro and carefully execute some
set of cursor positioning, mark, search, etc. keystrokes.  Switching
to the "window below" and taking advantage of whatever I had "cut"
or copied in the window above to paste, overwrite/insert into the
lower window.  Then, return to the "window above" for any additional
steps that needed to be performed there.  Back to the lower window, etc.

Once done, "end" the macro (taking care to make sure the cursors in
the source and destination windows are positioned appropriately so
this stored set of keystrokes could be applied to the *next* source
instance (line, field, etc.).

Then, lean on the "play keystroke macro" command and watch the
two windows scroll along as the cursor frenetically jumps around
applying the stored actions.

I found this *so* easy to do that it was the *first* technique
I would often apply -- even if there might have been some more clever
way of doing what I wanted.  Esp as it would let me *see* the changes
being applied ("Ooops!  I guess I don't really want to apply this
for the entire extent of the file!  Best stop here and undo back to
where I *should* have stopped!")

> By "still supported", I meant "bugs are fixed"
>
> No CVS integration needed.

It's interesting to see the different attitudes tools take towards
their "associates"!  I.e., does the editor invoke the VCS toolkit?
Or, does the VCS toolkit invoke the *editor*??  Everyone always wants
to drive the bus...

I've been setting up a Perforce server for one of the projects, here.
Needless to say, they want to think the world revolves around *them*!

> Working under windows when at work.

And *only* dealing with "source code"?  E.g., I find it tedious
having to bounce around between different toolchains where different
capabilities are present -- or, invoked/implemented in slightly
incompatible ways (hence liking the ability to be able to resort to
something as banal as vi(1) as needed).

> I don't want my spaces replace by tabs either  ;)
>
> Will give a try to Eclipse again, although don't like the screen real
> state it uses in things other than the files edited.

That's one advantage to using, e.g., vi(1) in separate xterm(1)s
under X.  Very little "wasted" real estate for "button bars",
status fields, etc.  Likewise, a no-frills window manager so you
don't have lots of decorated window frames!

[I have xterm(1) configured so I can easily change font sizes in
individual sessions -- though that currently also changes the
window geometry]

> Specially when I need to use larger and larger fonts as time goes by.
> (Not everybody has dual 30" monitors.) And what was that Saturn-like
> icon for?

Be thankful you're just writing code!  When preparing publications,
you want to see a good fraction of the page (to get a feel for how
it lays out, etc.) which drives text size down.  Yet, you still want
to be able to resolve different typefaces/styles conveniently
("is that italics?  or, just excessive jaggies from the lowered
relative resolution??")

There comes a point where you just can't get a monitor *big*
enough!!  :-/

[toc] | [prev] | [next] | [standalone]

#13249

On Thu, 29 Aug 2013 12:04:40 -0700, Don Y <this@isnotme.com> wrote:

>Hi Roberto,
>
>On 8/29/2013 7:01 AM, Roberto Waltman wrote:
>> Specially when I need to use larger and larger fonts as time goes by.
>> (Not everybody has dual 30" monitors.) And what was that Saturn-like
>> icon for?
>
>Be thankful you're just writing code!  When preparing publications,
>you want to see a good fraction of the page (to get a feel for how
>it lays out, etc.) which drives text size down.  Yet, you still want
>to be able to resolve different typefaces/styles conveniently
>("is that italics?  or, just excessive jaggies from the lowered
>relative resolution??")
>
>There comes a point where you just can't get a monitor *big*
>enough!!  :-/


A second video card and a 24 inch monitor in portrait mode will set
you back, what, $200?

[toc] | [prev] | [next] | [standalone]

#13251

Hi Robert,

On 8/29/2013 2:31 PM, Robert Wessel wrote:
> On Thu, 29 Aug 2013 12:04:40 -0700, Don Y <this@isnotme.com> wrote:
>
>> On 8/29/2013 7:01 AM, Roberto Waltman wrote:
>>> Specially when I need to use larger and larger fonts as time goes by.
>>> (Not everybody has dual 30" monitors.) And what was that Saturn-like
>>> icon for?
>>
>> Be thankful you're just writing code!  When preparing publications,
>> you want to see a good fraction of the page (to get a feel for how
>> it lays out, etc.) which drives text size down.  Yet, you still want
>> to be able to resolve different typefaces/styles conveniently
>> ("is that italics?  or, just excessive jaggies from the lowered
>> relative resolution??")
>>
>> There comes a point where you just can't get a monitor *big*
>> enough!!  :-/
>
> A second video card and a 24 inch monitor in portrait mode will set
> you back, what, $200?

I already have six 21" monitors in the office -- two on each
workstation.  Rotate one to have the aspect ratio of a "sheet
of paper" when working on documents -- the other can remain
"as is" to interact with the associated applications.

The problem with larger monitors is you need them further away
in order to see the page as a whole.  Then, the added detail
gets lost (vision degrades with age).

I've found it much more productive to *print* the pages of
interest and examine them in my hands.  Your eyes are very
capable of resolving fine detail WHEN CALLED UPON (they
are also very good at *ignoring* fine detail when necessary!).
Print a page at 1200dpi (even 600dpi for proofs) and you can
get a much better feel for the "product" than a 21 (or 24!)
inch monitor operating at a resolution of 7000 pels or
greater, vertically!

[There's a reason folks typeset documents at "magnified scale"...
you just can't see that sort of fine detail on commercial monitors
at 1:1!  *I* "cheat" a lot!  altering the colors associated
with certain tags so that I can rely on color cues in lieu of
being able to have a high degree of visual acuity.  E.g., perhaps
arranging for "emphasis" text (possibly italic?) to be displayed
in green -- as well as in the required typeface -- so that the
color cue frees me from having to question whether a particular
glyph has some slant/skew/boldness to it or not]

[toc] | [prev] | [next] | [standalone]

#13268

Robert Wessel <robertwessel2@yahoo.com> writes:

> A second video card and a 24 inch monitor in portrait mode will set
> you back, what, $200?

1920x1080 can be had at that price, but the better 1920x1200 ones start
around $300.

To me, it's not just about bigger.
-- 
Randy Yates
Digital Signal Labs
http://www.digitalsignallabs.com

[toc] | [prev] | [next] | [standalone]

#13267

Don Y <this@isnotme.com> writes:
> [...]
> There comes a point where you just can't get a monitor *big*
> enough!!  :-/

Not that I really need it, but I've been lusting on an HP ZR30W
for some time...  Currently using the ZR24W and it is excellent.
-- 
Randy Yates
Digital Signal Labs
http://www.digitalsignallabs.com

[toc] | [prev] | [next] | [standalone]

#13269

Hi Randy,

On 8/30/2013 5:37 PM, Randy Yates wrote:
> Don Y <this@isnotme.com> writes:
>> [...]
>> There comes a point where you just can't get a monitor *big*
>> enough!!  :-/
>
> Not that I really need it, but I've been lusting on an HP ZR30W
> for some time...  Currently using the ZR24W and it is excellent.

If you're just writing code or drawing schematics, you can get
a lot out of a generic display.  E.g., it's easy for me to have
9 (non-overlapping) xterms open on a single display concurrently
with very little problems reading what's displayed on each.  All
you're concerned with is selecting a typeface in which '1' and
'l', '0' and 'O', etc. are readily distinguishable.  (and, diodes
are easily differentiated from caps, resistors, etc.  :> )

But, when you're actually creating documents for publication,
you need to be able to resolve different type *styles* (e.g.,
italic vs. bold vs. bold italic vs. condensed, etc.), sizes
(e.g., sub/superscript), typefaces (san serif vs serif et al.)
and spacing/kerning.

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!

Some footnotes from that document (not sure if non-USASCII characters
will be visible, here):

1 Unqualified, the term “Bézier”, herein, shall refer to cubic Bézier 
curves.

2 All curves begin from the same P0. The choice of second control point, 
P1, is varied between each of the remaining points. The final control 
point, P3, is obvious on visual inspection.

3 Thus, C1 Continuity implies G1 Continuity. However, the reverse is not 
true.

4 For examples of these degenerate cases, see Special Cases.

Some issues that you need to be able to resolve, "visually", while
updating the document:

The first 'e' in Bezier carries an accent.

The opening and closing quotes surrounding the first instance of
Bezier in (1) are different characters/glyphs.  They must be
differentiable from "normal" double quotes.

"Cubic" in (1) is in italics as are "G1 Continuity" and "C1 Continuity".

Each digit in the selected footnote texts above are subscripts.

"Special Cases" in (4) is bold.

Recall, footnote text is 8 point.  With a 150dpi display, this
corresponds to ~16 pels tall -- including interline leading!
(i.e., the actual glyph from baseline to ascender is about 10-12
pels tall)  For subscripts within those footnotes, you're talking
about 6-8 pels.  I.e., resolving a 10 pt glyph "accidentally" copied
into footnote text (i.e., by pasting something cut from body text
*without* stripping the formatting information from it, first!) from
the normal 8 point text boils down to a few pels on each axis.
Resolving "X sub 1" vs. "X sub l" in footnote text would, at best, be
tedious/time consuming/prone to error!

[in fact, the effective bitmaps for the two subscript glyphs differ
by one -- maybe 1.5 -- pels!]

I won't even go into the issues involved with presenting complex
mathematical formulae with the large variety of symbols they
introduce.

OK, so what's a "150 dpi" display?  If you're viewing an 11" tall
sheet of paper "at full scale" (i.e., 1:1), that's ~1600 dots
vertically.

Using a 4:3 monitor in landscape mode would require a resolution
of 1600x2100 in an 18.5" diag display.  A 4:3 monitor in portrait
mode would require a resolution of 1200x1600 in a 14" diag display.

Using a 16:9 monitor in landscape mode requires a resolution of
1600x2850 in a 22.5" display.  In portrait mode, you'd need
900x1600 in a 13" display.

[My math may be off -- I haven't done this calculation in a few
years!]

I.e., you want *small* displays with high resolutions.  And, that
just barely gives you the visual resolution to determine what's
actually on the screen!

Most displays with higher resolutions (i.e., *better* than these
figures!) tend to be physically larger.  Then, you start having to
deal with "pages" that are too large to comfortably view (unless
you can lay the monitor *into* the desk surface -- how often do
you read an 11" tall sheet of paper "standing straight up" on
it's edge?

So, you either get used to typesetting at a much magnified scale
(which means you see less of the page and have a distorted view
of the page's overall presentation) *or* fight trying to resolve
these fine features in a *coarse* presentation... *or*, resort
to other tricks (like colored tags) or custom tools to parse
your documents on your behalf.

[toc] | [prev] | [next] | [standalone]

#13271

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?

> Some issues that you need to be able to resolve, "visually", while
> updating the document:
> 
> The first 'e' in Bezier carries an accent.
> 
> The opening and closing quotes surrounding the first instance of
> Bezier in (1) are different characters/glyphs.  They must be
> differentiable from "normal" double quotes.

That's a matter of Unicode support. Both é and the quotes are Unicode
characters.

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

> Each digit in the selected footnote texts above are subscripts.

OK,
  Thus, \term{$C_1$ Continuity} implies \term{$G_1$ Continuity}.
  However, the reverse is not true.

> "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}.

> 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).

> So, you either get used to typesetting at a much magnified scale
> (which means you see less of the page and have a distorted view
> of the page's overall presentation) *or* fight trying to resolve
> these fine features in a *coarse* presentation...

When working with the text, I don't care about overall page layout. And
when dealing with overall page layout, I don't have to be able to read
every accent and superscript. But the previewers have a Zoom function if
I need it anyway.

> *or*, resort
> to other tricks (like colored tags) or custom tools to parse
> your documents on your behalf.

I wouldn't call using LaTeX a custom tool or a trick.


  Stefan

[toc] | [prev] | [next] | [standalone]

#13282

Hi Stefan,

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!

E.g., when I typed up the draft text for the Bezier article,
I had planned to have an initial illustration that showed a
set of four *fixed* control points and how the order in which
they were "visited" could radically alter the shape of the
resulting curve:  draw the bezier associated with (A,B,C,D)
in solid red; the (A,C,B,D) bezier in dotted green; and the
dashed (A,D,B,C) in blue.  This packs three illustrations
in the space of one!  (e.g., ~3 column inches)

Following this, I described the role of the control polyline
as a hint towards the shape of the resulting curve.  And,
what better way to illustrate this than to show the changes in
the shape of the control polygon for these three examples!

When the draft text was done and I started building the document,
it was *really* obvious that the same "three illustrations in
one figure" trick wasn't going to work -- the control polygons
overlap (d'uh!) so its virtually impossible to see which
polygon is associated with each curve.

Now, the "one" figure has to be replaced by three NONoverlapping
figures.  Or, by three *consecutive* figures.  In either case,
now an entire column spent on those three illustrations.  This
moves a lot of text off the page -- causing the layout of subsequent
pages to change.

Similarly, when deriving the equations for the tangents to the
curve, some of the equations were too wide to fit within a column
(you only know that when the equations are typeset!).  You then
have to decide:  do I "fold" the equation so it fits in a
single column?  or, do I insert a frame in which the equation
will reside and have that frame straddle both columns?  In each
case, the layout of everything around it is altered (e.g., you
ideally want the description associated with the derivation to
be present with the equation(s) also visible).

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.  For example,
in the first 10 pages of that document, I have:
- 31 "display" (i.e., freestanding) equations (or "derivations")
- 23 figures/illustrations
- 3 tables
- 7 interactive demos

[The document is over 30 pages -- each pretty much the same sort
of complexion as these first 10]

Each of these are "large (visual) objects" that can't be split.
I.e., can't have half an illustration on one page and the other
half on the page following!  Because of that, each causes the
surrounding text to be severely chopped up (unless you allow the
objects to "float" free of the associated text).

>> Some issues that you need to be able to resolve, "visually", while
>> updating the document:
>>
>> The first 'e' in Bezier carries an accent.
>>
>> The opening and closing quotes surrounding the first instance of
>> Bezier in (1) are different characters/glyphs.  They must be
>> differentiable from "normal" double quotes.
>
> That's a matter of Unicode support. Both é and the quotes are Unicode
> characters.

You missed the point.  This post was concerned with size of *display*.
I.e., can you discern which type of accent is present on the 'e' when
the glyph is ~6 pts?  I.e., when there are ~10 pels in its height
(so the accent is a pel or two).  You *can* when it's printed on
a sheet of paper, professionally!  (try it)

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

>> Each digit in the selected footnote texts above are subscripts.
>
> OK,
>    Thus, \term{$C_1$ Continuity} implies \term{$G_1$ Continuity}.
>    However, the reverse is not true.

>> "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!  It's still got to be the same size as the non-bold
version -- yet, you need to be able to *see* that it is actually
bold (do you allow the loops in the a/e/p to close to make
room for the extra pels that need to be inked?)

>> 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?  (even Knuth did that
with _The TeXbook_ series!)  Then, when you "notice" something
is in the wrong typeface/style/layout, go back to the TeX
originals, edit it (in EMACS, of course!) and rerun the TeX
executable?

And, how are you manipulating all of those illustrations, tables,
equations?  Just *hoping* they fall into convenient spots?

>> So, you either get used to typesetting at a much magnified scale
>> (which means you see less of the page and have a distorted view
>> of the page's overall presentation) *or* fight trying to resolve
>> these fine features in a *coarse* presentation...
>
> When working with the text, I don't care about overall page layout. And
> when dealing with overall page layout, I don't have to be able to read
> every accent and superscript. But the previewers have a Zoom function if
> I need it anyway.

Of course you have to be able to read accents and superscripts!
How do you catch errors that you may introduce while *tweeking*
the text to adjust the layout?  Fold an equation to make it fit
*in* a column:  "Does the folded form still represent the same
relation?  Or, have I omitted an operator?  Or, included a
duplicate?

How do you decide that something needs a footnote added (to
introduce an issue that qualifies the discussion without acting
as a distraction in body text)?  Then, respond to the *new*
layout changes that this causes in the document?  ("Crap!
That forced this illustration onto the next page -- leaving
a big chunk of whitespace, here and altering the visual
aesthetics of each of the subsequent pages.  I *thought*
I was just about done but I see there's a lot more tweeking
required...")

Remember, there's no compiler or lint to check to see that
what you wrote is what you wanted it to be!  And, diff(1) is
essentially useless (for any significant text motion).

>> *or*, resort
>> to other tricks (like colored tags) or custom tools to parse
>> your documents on your behalf.
>
> I wouldn't call using LaTeX a custom tool or a trick.

Have you actually *watched* how publications are made,
professionally?  On average, I produce about a thousand photo-ready
pages a year -- and that's just a "cost of doing business" (not
what I *do* for a living).  Believe me, I sorted out where the
"costs" (i.e., time) lie in this process a long time ago!  :-/
I'm probably far more efficient at it than most "departments"
charged with this sort of activity -- because I have it in mind
when writing the specifications, designing the hardware,
crafting the code, developing test procedures and preparing
user documentation.  So, I *plan* on leveraging each of these
activities into each other (instead of their "free standing"
implementations in most organizations)

That's the problem with "programmers" -- they see everything as
a piece of code instead of a specific application domain unto
itself with its own rules, traditions, criteria, etc.

[Talk to RMS and *every* problem can be solved by "just" making
the source code available.  The fact that the folks using a
product might have no idea what to *do* with the source code
is immaterial -- "they can hire someone"  :( ]

Talk to a programmer about VCS and they'll argue back and forth
CVS/GIT/Hg/SVN/RCS/p4/etc. -- totally oblivious to the fact that
there are "documents" (electronic objects) that exist that
ARE NOT "source code".  Yet, squeal like a stuck pig if "forced"
to use a VCS that more heavily favors some *other* department's
needs (though never seeing the hypocrisy of forcing that other
department to use the tools that *they* prefer!)

"Everything looks like a nail"

[toc] | [prev] | [next] | [standalone]

#13291

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.

> 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.

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

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. 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.

>>> 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.


  Stefan

[toc] | [prev] | [next] | [standalone]

#13293

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...]

[toc] | [prev] | [next] | [standalone]

#13295

Don Y wrote:
> On 9/1/2013 11:21 AM, Stefan Reuther wrote:
>>>> 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>,

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).

>> 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.

> 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.

>> 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".)

> 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.

"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 :)

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.

It's not a good workflow for things like party invitation posters. But
for tech manuals I find it optimal.

> 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.)


  Stefan

[toc] | [prev] | [next] | [standalone]

#13298

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

[toc] | [prev] | [next] | [standalone]

#13299

Don Y <this@isnotme.com> writes:
> [...]

Don,

Not that I want to be a usenet topic policeman, but why would a group on
embedded firmware be interested in how you typeset your documents? It
just seems like an odd place to attempt to stimulate such a discussion.
-- 
Randy Yates
Digital Signal Labs
http://www.digitalsignallabs.com

[toc] | [prev] | [next] | [standalone]

#13300

Hi Randy,

On 9/2/2013 4:39 PM, Randy Yates wrote:

> Don,
>
> Not that I want to be a usenet topic policeman, but why would a group on
> embedded firmware be interested in how you typeset your documents? It
> just seems like an odd place to attempt to stimulate such a discussion.

As with *most* USENET posts, it was an evolution triggered by the last
paragraph of my initial reply to Roberto's initial post in this thread:

    > Specially when I need to use larger and larger fonts as
    > time goes by.  (Not everybody has dual 30" monitors.) And
    > what was that Saturn-like icon for?

    Be thankful you're just writing code!  When preparing publications,
    you want to see a good fraction of the page (to get a feel for how
    it lays out, etc.) which drives text size down.  Yet, you still want
    to be able to resolve different typefaces/styles conveniently
    ("is that italics?  or, just excessive jaggies from the lowered
    relative resolution??")

    There comes a point where you just can't get a monitor *big*
    enough!!  :-/

which was related to the effectiveness of particular editors
in massaging source documents.

The beautiful thing about USENET is, you don't have to read
anything you don't want to read!  :>  E.g., I ignore all the
political rants.

OTOH, you *may* pick up some tidbit about how others work if
you *do* chose to read something *apparently* unrelated.  I've
learned about lots of tools and technologies from "off topic"
digressions over the years.  Things that I probably would never
have sought out had I not heard others discussing them (favorably
and unfavorably).

Thankfully, I always post from the same account, with the same
"From" line, etc. so it's a lead pipe cinch for folks to add me
to their kill files if they so desire.  A bit more involved for
me to do the same to those folks who enjoy profanity, political
rants, etc.

<shrug>

[toc] | [prev] | [next] | [standalone]

Page 3 of 4 — ← Prev page 1 2 [3] 4  Next page →

Back to top | Article view | comp.arch.embedded

csiph-web