From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.help Subject: Re: Emacs Book Vs Emacs Manuals Date: Sat, 16 May 2015 10:32:25 +0300 Message-ID: <838ucpgepi.fsf@gnu.org> References: <87fv77barj.fsf@gnu.org> <87zj5fgpd8.fsf@newcastle.ac.uk> <83h9rnp0yy.fsf@gnu.org> <83zj5enihg.fsf@gnu.org> <554EFEFD.6090908@gmail.com> <833834o4rv.fsf@gnu.org> <834mnjm73d.fsf@gnu.org> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=windows-1252 Content-Transfer-Encoding: QUOTED-PRINTABLE X-Trace: ger.gmane.org 1431761571 20899 80.91.229.3 (16 May 2015 07:32:51 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sat, 16 May 2015 07:32:51 +0000 (UTC) To: help-gnu-emacs@gnu.org Original-X-From: help-gnu-emacs-bounces+geh-help-gnu-emacs=m.gmane.org@gnu.org Sat May 16 09:32:42 2015 Return-path: Envelope-to: geh-help-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1YtWaQ-0005iU-El for geh-help-gnu-emacs@m.gmane.org; Sat, 16 May 2015 09:32:42 +0200 Original-Received: from localhost ([::1]:33851 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YtWaP-0008L2-Dh for geh-help-gnu-emacs@m.gmane.org; Sat, 16 May 2015 03:32:41 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:36242) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YtWaD-0008Ku-Ik for help-gnu-emacs@gnu.org; Sat, 16 May 2015 03:32:30 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1YtWaA-00079i-Br for help-gnu-emacs@gnu.org; Sat, 16 May 2015 03:32:29 -0400 Original-Received: from mtaout21.012.net.il ([80.179.55.169]:62972) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YtWaA-00076G-3z for help-gnu-emacs@gnu.org; Sat, 16 May 2015 03:32:26 -0400 Original-Received: from conversion-daemon.a-mtaout21.012.net.il by a-mtaout21.012.net.il (HyperSendmail v2007.08) id <0NOF00I00LXDF800@a-mtaout21.012.net.il> for help-gnu-emacs@gnu.org; Sat, 16 May 2015 10:32:24 +0300 (IDT) Original-Received: from HOME-C4E4A596F7 ([87.69.4.28]) by a-mtaout21.012.net.il (HyperSendmail v2007.08) with ESMTPA id <0NOF00IFNM9ZG100@a-mtaout21.012.net.il> for help-gnu-emacs@gnu.org; Sat, 16 May 2015 10:32:24 +0300 (IDT) In-reply-to: X-012-Sender: halo1@inter.net.il X-detected-operating-system: by eggs.gnu.org: Solaris 10 X-Received-From: 80.179.55.169 X-BeenThere: help-gnu-emacs@gnu.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: Users list for the GNU Emacs text editor List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: help-gnu-emacs-bounces+geh-help-gnu-emacs=m.gmane.org@gnu.org Original-Sender: help-gnu-emacs-bounces+geh-help-gnu-emacs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.help:104463 Archived-At: > From: Vaidheeswaran C > Date: Sat, 16 May 2015 11:20:09 +0530 >=20 > >> You can help me define the "glue". > > > > It's that stuff that guides the reader from one feature to anothe= r, > > 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 so= me > > sense, and facilitate understanding and memorizing them. >=20 > DITA and Robert E Horn's work on Structured Writing could __inform_= _ > our efforts. See below for more details. >=20 > Here is a quick summary of DITA (from Wikipedia page). >=20 > | DITA content is created as topics. Typically, each topic covers a > | specific subject with a singular intent, for example, a conceptua= l > | topic that provides an overview, or a procedural topic that expla= ins > | how to accomplish a task. I think the Emacs manuals already conform to this. > On the topic of "glues", >=20 > | See > http://www.scriptorium.com/2009/12/assessing-dita-as-a-foundation-f= or-xml-implementation/ >=20 > | 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. >=20 > | One topic (sorry!) of heated discussion is the issue of =93glue t= ext,=94 > | 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 th= at > | 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_Archi= tecture > | > | 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 elem= ent > | 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 describ= es > | 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 t= he > | 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 usu= ally > | 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 th= e "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 tool= s 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.