delorie.com/archives/browse.cgi   search  
Mail Archives: djgpp-workers/1998/08/23/17:15:24

Comments: Authenticated sender is <mert0407 AT sable DOT ox DOT ac DOT uk>
From: "George Foot" <george DOT foot AT merton DOT oxford DOT ac DOT uk>
To: djgpp-workers AT delorie DOT com
Date: Sun, 23 Aug 1998 22:13:33 +0000
MIME-Version: 1.0
Subject: Patch to mkdoc and re: portability information
Reply-to: george DOT foot AT merton DOT oxford DOT ac DOT uk
Message-Id: <E0zAhTX-0008K6-00@sable.ox.ac.uk>

Hello

At last I have some time on my hands, so I decided to work on the
portability information again.  Here's a patch for
`src/mkdoc/mkdoc.cc', based on the version in the 980628 alpha.  It
incorporates changes I made back in March, and a few others made
today.  The changes alter the way the information is tracked inside
mkdoc and make it slightly more flexible.

The current structure is based around having the following lines in 
the documentation for each function:

    @subheading Portability
    
    @portability ansi ~posix !borland

If `ansi', `posix' and `borland' were categories, this would mean
that the function would be portable to ANSI and partially to POSIX,
but not to Borland.

When a function is only partially portable to a target (like the 
`posix' target above) you can give a descriptive note explaining why 
it's not quite portable to that platform.  Put this line:

    @port-note posix Feature X is meaningless in a DOS environment

before the `@portability' line; or, write:

    @port-note posix
    Feature X is meaningless in a DOS environment

This way, you can write longer notes split across several lines 
(they'll be reformatted by makeinfo, of course).

You can write notes for as many targets as you like, not just for
ones marked with `~', but I think it's better to avoid unnecessary
notes, especially if the reason for the note is already stated in
the documentation for the function.  The patched mkdoc is capable of
including multi-paragraph notes, but this is just a safety net in
case for some function it really is necessary to say a lot.  

Here's an example, for the `fflush' function:

    @subheading Portability
    
    @port-note Borland 
    Borland has an extension to @code{fflush}; it lets you fflush an 
    input stream, purging all characters.  DJGPP does not support this.
    
    @portability ansi posix ~borland

I don't actually think that's a good place for a note, but it's just
an example. 

Please comment on this.  I personally think we have enough to start 
adding this information to the documentation, but if you disagree 
let's change it.  I think it's better to have the processing done by 
`mkdoc.cc' itself rather than through Texinfo macros.

If everybody approves of the general system outlined above, we need 
to decide what the categories should be.  This patched mkdoc.cc has 
two catogries -- "ansi" and "posix".  Of course it's simple to add 
more.  It's also simple to change the format of the Texinfo output if 
you don't like it.

When we discussed this before, people disagreed about which 
categories we should use; should DOS be a category all by itself, or 
should each DOS compiler get its own category?  What about Windows 
compilers?  What about Unix compilers -- can Unix be a single 
category, or would we need to list a lot of flavours?

Personally I think DOS compilers should be a single category; we can
list individual compilers' differences in notes if it's thought to be
necessary.  I don't know about Unix compilers; presumably they all
support ANSI and POSIX but after that do they differ a lot from each
other?  If so then we should either give them separate categories or
not list them at all -- or just say that the function is not
universally portable to Unix systems, if only some have it.  Again
we could list in notes which do/don't if you like.

Having a very large number of categories will be unwieldy in the
documentation, but they don't all have to be mentioned in every
function.  We could have a generic DOS category, and also one
category for each DOS compiler, and only list individual compilers
when they're different from the normal DOS trend.  I think Eli said 
this was rare, anyway.

So there are many options.  I don't think we need to decide this 
immediately; assuming that ANSI and POSIX are definite categories we 
can go ahead and put that information into the .txh files, adding 
other categories later.  Even just having the ANSI/POSIX portability 
information would be an improvement on what we have now (i.e. no 
portability information).

We also need to decide where in the documentation the portability
information should go; I suggest putting it just before the example
in nodes which have an example, or at the end of the node if there
is no example.

Finally we need to go through the .txh files adding the information.  
This is a big task, but not very difficult to do at a simple level, 
since the header files already show whether a function is defined in 
ANSI or POSIX or neither.

I don't think it's possible to be more specific all through the docs
(e.g. mentioning how a function is not quite POSIX) unless you have
experience using that function and already know how it is different.
I think that sort of detail needs to be added afterwards bit by bit. 
In extreme cases (like `stat') there's already a lot of information
given about how the function is awkward to implement in DOS.

-- 
george DOT foot AT merton DOT oxford DOT ac DOT uk

- Raw text -


  webmaster     delorie software   privacy  
  Copyright © 2019   by DJ Delorie     Updated Jul 2019