Re: [AD] Doc perusing

[Grzegorz A. H. <gr...@ti...>]

On 2004-08-23, Chris <kc...@st...> wrote:
> In readme.txt, it mentions the Alleg5 mailing list. I don't really
> know what Bob and Peter are planning to do with the list yet,
> but I personally think it's safe to say it's rather defunct. I
> don't think we have to remove the reference to it, but I think
> a little note about its current status should go in.

Everybody can see the status by looking at the archives. All the
mailing lists have gone through periods of emptiness.

> In const.txt, there's this in the closing paragraph:

You forgot your proposed change.

Index: docs/src/const._tx
===================================================================
RCS file: /cvsroot/alleg/allegro/docs/src/const._tx,v
retrieving revision 1.5
diff -u -r1.5 const._tx
--- docs/src/const._tx  7 Sep 2003 19:11:52 -0000       1.5
+++ docs/src/const._tx  26 Aug 2004 07:35:34 -0000
@@ -123,11 +123,10 @@
 @heading
 Finally...
 
-I have only tested this myself on DJGPP 2.95.2, so if you have experiences
-of it not working (I have tried to get Linux and BeOS ports right, but I've
-no guarantee it worked...) email me the *exact* error message and I will
-fix it. You can also contact the Allegro mailing list; see `Contact info'
-in the Allegro documentation (readme.txt).
+Allegro `const'-correctness has been tested for quite enough time to say
+that it is working OK. However, if you still find problems with a compiler,
+please contact the Allegro mailing list; see `Contact info' in the Allegro
+documentation (readme.txt).
 
 Email: <email>lwi...@lw...</a>.
 
> Is it alright to call allegro_message if allegro_init fails
> like that?

Yes. Otherwise it would be useless. Proposed patch.

Index: docs/src/allegro._tx
===================================================================
RCS file: /cvsroot/alleg/allegro/docs/src/allegro._tx,v
retrieving revision 1.248
diff -u -r1.248 allegro._tx
--- docs/src/allegro._tx        24 Aug 2004 08:39:18 -0000      1.248
+++ docs/src/allegro._tx        26 Aug 2004 07:44:37 -0000
@@ -213,13 +213,15 @@
 @@void @allegro_message(const char *text_format, ...);
 @xref set_uformat
 @eref Available Allegro examples
-   Outputs a message, using a printf() format string. This function must 
-   only be used when you aren't in graphics mode, eg. before calling 
-   set_gfx_mode(), or after a set_gfx_mode(GFX_TEXT). On platforms that have 
+   Outputs a message, using a printf() format string. Usually you want to
+   use this to report messages to the user in an OS independant way when some
+   Allegro subsystem (or allegro itself) cannot be initialised. But you must
+   not use this function if you are in a graphic mode, only before calling
+   set_gfx_mode(), or after a set_gfx_mode(GFX_TEXT). On platforms that have
    a text console (DOS and Unix) it will print the string to that console,
    attempting to work around codepage differences by reducing any accented
    characters to 7-bit ASCII approximations, and on platforms featuring a
-   windowing system it will bring up a GUI message box. Example:
+   windowing system it will bring up a blocking GUI message box. Example:
 <codeblock>
       ret = allegro_init();
       if (ret != 0) {

> The cpu_* vars say this: "You can read this variable after
> you have called check_cpu() (which is automatically called by
> allegro_init())."  It seems a little over-the-top to say you can
> only read it after running check_cpu, then to immediately say
> check_cpu is called for you.

There might be people willing to use this before allegro_init().

> The PACKFILE typedef lists this as part of the struct:
>    int hndl;                   - DOS file handle
> I think that would be better worded as 'system file handle'.

Yes. Commited.