Re: Emacs Book Vs Emacs Manuals

[Vaidheeswaran C <vaidheeswaran.chinnaraju@gmail.com>]

On Monday 11 May 2015 09:36 PM, Eli Zaretskii wrote:
>> From: Vaidheeswaran C <vaidheeswaran.chinnaraju@gmail.com>
>> Date: Mon, 11 May 2015 11:00:09 +0530
>>
>>>> What I call as "A Book", may not in actuality be a book as it is
>>>> conventionally understood and consumed.
>>>
>>> Then what is it?  And why would people want to use it, instead of
>>> googling?
>>>
>>> Without some "glue", there's no added value to a book that just brings
>>> together unsorted tops that are already available on the Web.
>>
>> 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.


For the sake of discussion, let us pretend that my proposed "Book"
will be task-oriented and include guidelines (platform-specific or
locale-specific).  Each task-oriented node will cross-reference some
or more of standard Info nodes.  (The cross-reference can be to a link
to a concept or a node in the glossary).

----------------------------------------------------------------

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.

----------------------------------------------------------------

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

----------------------------------------------------------------

Works of Robert E. Horn may be of some interest to current
discussion. (See http://www.amazon.com/Robert-E.-Horn/e/B000APJGAU).
If any of you is familiar with the works, please check-in ...