Sender: rich AT phekda DOT freeserve DOT co DOT uk
Message-ID: <3E428516.6E9BF039@phekda.freeserve.co.uk>
Date: Thu, 06 Feb 2003 15:53:58 +0000
From: Richard Dawe <rich AT phekda DOT freeserve DOT co DOT uk>
X-Mailer: Mozilla 4.77 [en] (X11; U; Linux 2.2.23 i586)
X-Accept-Language: de,fr
MIME-Version: 1.0
To: djgpp-workers AT delorie DOT com
Subject: Re: Add @tindex for types in docs [PATCH]
References: <E18fmrW-0000gG-00 AT phekda DOT freeserve DOT co DOT uk>
	 <Pine DOT OSF DOT 4 DOT 51 DOT 0302041153300 DOT 10610 AT sirppi DOT helsinki DOT fi>
	 <3E3FDCB5 DOT D2875A7E AT phekda DOT freeserve DOT co DOT uk> <Pine DOT OSF DOT 4 DOT 51 DOT 0302051322280 DOT 1814 AT sirppi DOT helsinki DOT fi> <2561-Wed05Feb2003174006+0200-eliz AT is DOT elta DOT co DOT il>
Content-Type: text/plain; charset=us-ascii
Content-Transfer-Encoding: 7bit
Reply-To: djgpp-workers AT delorie DOT com

Hello.

Eli Zaretskii wrote:
> 
> > Date: Wed, 5 Feb 2003 13:45:03 +0200 (EET)
> > From: Esa A E Peuha <peuha AT cc DOT helsinki DOT fi>
> >
> > I think that it's best not to have any duplicate definitions.
> 
> Maybe it is, maybe it isn't.  Think about a user who wants to use
> `fstat', but is told that `struct stat' is documented on the `stat'
> page.  Such a user will need to jump between these two pages back and
> forth all the time.  Not many DJGPP users know enough secrets of the
> Info reader that will allow them to do that and remain sane (e.g.,
> how many of those who read this list know that the stand-alone Info
> reader can show two pages at the same time in a split-window display?
> try "Ctrl-x 2" some day).

I didn't know about Ctrl-x 2, but I unconciously use the Emacs keystrokes. I
learnt Emacs after info, so perhaps I just don't expect info to be Emacs-like
enough?

> But I'm not going to veto any changes that delete multiple
> descriptions of data types.  Just keep this gotcha in mind before you
> decide.
[snip]

It seems to me that the main concern is maintaining the descriptions of data
types. E.g.: if someone adds a field, then you need to update all the nodes ==
tedious and error-prone.

One solution would be to move the description into a separate file and
@include that file.

I can see a couple of problems with that solution:

(a) makeinfo would need multiple -I <directory> options, so that the data type
description files can be found.

(b) Less seriously, what to call the files? We have to name them, so that
mkdoc doesn't find them. We already use .txi and .txh. So .txd? .txp?

Problem (a) could be solved by putting all the data-type definitions in one
source directory. But that moves them away from the documentation they go
with.

Another solution to problem (a) is to get mkdoc to do the hard work. mkdoc
could generate a file containing all the -I options. Then we could invoke
makeinfo like this:

    makeinfo --no-split @makeinfo.opt libc.tex

Bye, Rich =]

-- 
Richard Dawe [ http://www.phekda.freeserve.co.uk/richdawe/ ]