Re: Emacs Book Vs Emacs Manuals

[Eli Zaretskii]

> From: Vaidheeswaran C <vaidheeswaran.chinnaraju@gmail.com>
> Date: Sat, 16 May 2015 11:20:09 +0530
> 
> >> You can help me define the "glue".
> >
> > It's that stuff that guides the reader from one feature to another,
> > and generally allows the reader to make sense out of a huge pile of
> > loosely related features.
> >
> > E.g., when you describe commands that act on buffers, they should be
> > described in some methodical manner, and the order should make some
> > sense, and facilitate understanding and memorizing them.
> 
> DITA and Robert E Horn's work on Structured Writing could __inform__
> our efforts.  See below for more details.
> 
> Here is a quick summary of DITA (from Wikipedia page).
> 
> | DITA content is created as topics. Typically, each topic covers a
> | specific subject with a singular intent, for example, a conceptual
> | topic that provides an overview, or a procedural topic that explains
> | how to accomplish a task.

I think the Emacs manuals already conform to this.

> On the topic of "glues",
> 
> | See
> http://www.scriptorium.com/2009/12/assessing-dita-as-a-foundation-for-xml-implementation/
> 
> | The topic-oriented architecture requires that authors create
> | modular, self-contained information. For content creators who are
> | accustomed to working on cohesive books, this can be rather a
> | difficult transition.
> 
> | One topic (sorry!) of heated discussion is the issue of “glue text,”
> | the content that provides coherent transitions from one topic to
> | another. Some argue that glue text is unnecessary and that
> | transitions are overrated; at the other extreme is the opinion that
> | modules without transitions are unusable. If you belong to the
> | latter group, keep in mind that implementing transitional text in
> | DITA is quite difficult. Transition text that makes sense in one
> | context might not be relevant in another.

That's not the "glue" I alluded to.

> | From http://en.wikipedia.org/wiki/Darwin_Information_Typing_Architecture
> |
> | Information typing
> |
> | DITA includes three specialized topic types: Task, Concept, and
> | Reference. Each of these three topic types is a specialization of a
> | generic Topic type, which contains a title element, a prolog element
> | for metadata, and a body element. The body element contains
> | paragraph, table, and list elements, similar to HTML.
> |
> | - A (General) Task topic is intended for a procedure that describes
> |   how to accomplish a task. A Task topic lists a series of steps
> |   that users follow to produce an intended outcome. The steps are
> |   contained in a taskbody element, which is a specialization of the
> |   generic body element. The steps element is a specialization of an
> |   ordered list element.
> |
> | - Concept information is more objective, containing definitions,
> |   rules, and guidelines.
> |
> | - A Reference topic is for topics that describe command syntax,
> |   programming instructions, and other reference material, and usually
> |   contains detailed, factual material.

Again, I think we already do all that in the Emacs manuals, where
appropriate.

But please note the catch in this approach, if used indiscriminately:
the number of potential "Tasks" that an Emacs user can face is
virtually infinite.  These tasks break into certain "building blocks",
which are combined in many different ways.  If you always describe the
"tasks", then you will need to repeat the description of these
building blocks time and time again, which is a disadvantage.

IOW, the above methodology is suitable only to relatively simple tools
that support a small number of well-defined tasks.  Emacs is not like
that, especially if you take ELisp into consideration, because that's
a reasonably general-purpose programming language, where the
task-based approach is unsuitable, IMO.