Mail Archives: djgpp-workers/1998/02/24/21:51:35
On Tue, 24 Feb 1998, DJ Delorie wrote:
> Long comments should be possible, but not necessarily convenient.
>
> The need for long comments in the portability section should be
> limited (that was a request, not an observation). The only case where
> a portability issue should be discussed at length is when DJGPP
> deviates from the expected (or defined) functionality. In that case,
> the note should go in the regular documentation, not the portability
> section.
I agree here -- these cases are already mentioned in the docs in some
places.
> Notes in the portability section should be limited in
> length, because I expect we'll be talking about other compilers here,
> which is not the goal of the djgpp documentation. Short notes, like
> "bc3 - needs <stddef.h>" or "msc - only two parameters" are enough;
> people who really need more information (about porting *to* those
> compilers) should have those manuals handy. People porting to djgpp
> from those compilers should find the info they need in the main body
> of the documentation.
This is true. At the lowest level all that is required is the
yes/no/partially information -- if `yes' then it will work, if `no' then
it won't, and if `partially' then it will need adapting. In the case of
`no' you have to look for a new function; in the case of `partially' you
either find a more portable function or read the docs for the other
systems. If your goal is to make code portable across many systems, the
latter isn't really practical.
> I guess this boils down to "what's the portability section for?"
>
> Here's my opinion: it's for people who want to write portable code.
> Those people need to know not only how djgpp does it (the regular
> docs) but also enough information to decide if they want to avoid a
> particular function because of portability reasons. This section
> should have enough information to make that decision, and no more.
Fair enough. I think though that if the `more' is very small then it
could be added (e.g. headers used on other DOS compilers).
> > Perhaps I'm confused, but from DJ's example it looked as though it would be
> > possible for the "keywords" to be non-magical. That is, any word could be
> > used as a header instead of "ANSI" or "Borland", etc. I'd like to suggest we
> > do that, so we don't have to hack `mkdoc' again each time we want to add
> > something.
> >
> > So the keywords would only be "key" in the sense that we'd standardized on
> > them for consistency, not that there's something special about them.
>
> Actually, I *was* thinking of hardcoding them into mkdoc, but I
> suppose mkdoc could read a separate config file that gives the
> expected tokens (mkdoc can report on others it finds) with full names
> and the order they are to be listed in.
OK. Last night I modified mkdoc to support everything discussed apart
from the catenation of lines using \. I did this based upon the v2.01
mkdoc; that's all I had on my machine, which isn't connected to the
internet. I'll check that it applies to v2.02 also shortly and post it.
IMHO we shouldn't have arbitrary keys defined by the .txh files -- that
will just result in inconsistency and confusion. Currently my modified
mkdoc has a couple of arrays at the start like so:
: #define NUM_PORT_TARGETS 2
:
...
:
: /* Tokens for use in .txh files */
: char *port_target[NUM_PORT_TARGETS] = { "ansi", "posix" };
: /* Strings to output in .txi files */
: char *port_target_string[NUM_PORT_TARGETS] = { "ANSI", "POSIX" };
I referred to the keys as `tokens' here. The first array gives the valid
tokens, and the second gives the `nice' output for the .txi files. For
example, at present:
@portability ansi ~posix
would output:
ANSI, partially POSIX
I know this isn't the table we considered before, and it doesn't quite
make sense; my texinfo wasn't good enough to generate that table from
memory and my version of texinfo doesn't support multitable (and hence
doesn't document it) so I just put in the above quickly. Modifying the
output format is very simple -- there are some new methods in the Node
struct, one of which does all the .txi output.
As I said, I don't think adding new tokens should be too trivial -- we
don't want people doing it willy-nilly. If a new token is added, all
functions that don't mention that token are documented to be unportable to
that target. This could easily be changed, of course, if people don't
like it.
To add new tokens, though, you just need to increase the #define, add
new strings to the arrays, and recompile. To me this doesn't seem to be a
problem.
At present my mkdoc issues warning messages if it discovers an
unrecognised portability token or an empty port-note. I wasn't sure
whether or not it should do (mkdoc doesn't give any other error messages)
but it's easier to take them out than it is to add them.
The catenation with `\' won't work very well with what I've done at the
moment because my code is only passed one line of the file at a time. The
obvious way to fix this would be to make the `\' catenation work
everywhere in .txh files, by modifying mkdoc's file reading section (in
scan_directory IIRC). Any objections to this?
I'd like to suggest an alternative to this though. The real need for
longish notes is where a function differs across a category (e.g. DOS or
Unix) in different ways for different systems within that category. We
could make this work by giving several notes in the same category, and
putting them all under the same note number in the output, i.e.:
@port-note dos Borland doesn't have this function.
@port-note dos MS prototypes this in <foo.h>.
@portability ~dos
results in something like:
Portable to DOS (1)
(1) Borland doesn't have this function.
MS prototypes this in <foo.h>.
To me this seems sensible, but the catenation might be worth adding as
well, in case it is needed.
--
george DOT foot AT merton DOT oxford DOT ac DOT uk
ko tavla fo la lojban
- Raw text -