Re: [AD] docs patch

[ Thread Index | Date Index | More lists.liballeg.org/allegro-developers Archives ]


> Attached is a version that is very slightly less condescending ;-)

Indeed. But I'm very picky these days:

+   Important: as soon as you are finished reading or writing a file using an
+   encryption password, please remember to call packfile_password(NULL) again
+   to return to unencrypted mode.

Why 'again' ? Is it mandatory to have called 'packfile_password(NULL)' previouly ?

> I'm not sure I understand the part about encrypted chunks though.

+   If you are using encrypted chunks, you must restore the password that was
+   active at the time the chunk was opened _before_ closing the chunk. After
+   the chunk is closed, you can call packfile_password(NULL) again.

Why this idea of restoring ? May the password vanish meanwhile ? And again, the last
sentence implicitly says that you can't call 'packfile_password(NULL) ' meanwhile.

+   Personal bias: IMHO this function is rather badly thought out. It affects
+   absolutely _all_ future packfile operations, including packfiles that are
+   implicitly opened by Allegro, e.g. during a call to load_bitmap(). My
+   advice is to not touch this function if you can avoid it. If you wish to
+   obfuscate game data so that curious people will not accidentally see
+   spoilers, may I recommend good old ROT-13?

I don't think the docs are the right place for such a comment. Let's be terse.


Here's my attempt:

+  Important: as soon as you are finished reading or writing a file using an
+  encryption password, please remember to call packfile_password(NULL)
+  to return to unencrypted mode. This mode is mandatory in order to use
+  other Allegro routines that operate on files, such as load_bitmap().

+   If you are using encrypted chunks, you must make sure that the password
+   that was active at the time the chunk was opened is still active _before_
+   closing the chunk. This is guaranteed to be true if you didn't call the
+   packfile_password() routine in the meantime. Once you are done with
+   encrypted chunks, call packfile_password(NULL) as explained above.


Vincent, could you explain the justification of your patch ? I suppose the
password can't change without calling packfile_password(). Is that true ?

--
Eric Botcazou
ebotcazou@xxxxxxxxxx



Mail converted by MHonArc 2.6.19+ http://listengine.tuxfamily.org/