








                    [1mAdPlug Hacking HOWTO[0m

                [4mSimon[24m [4mPeter[24m [4m<dn.tlp@gmx.net>[0m


[1m1.  Introduction[0m


     This  document  gives some coding guidelines for people
wishing to hack around in AdPlug. Be sure to also  read  the
overall  and  system-specific INSTALL files in the distribu-
tion's base directory to learn more about the build systems.


[1m2.  Coding Style[0m


     I  do not really enforce any coding style guidelines (i
don't adhere to any style guidelines myself, so... ;) ), but
it  would  be  nice  if you follow the overall coding style,
used throughout most of AdPlug's source files. If you don't,
that's perfectly okay, too.


     Most   of  today's  "super-intelligent"  editors,  like
MSVC's one or GNU Emacs' c-mode, have their own idea of what
the  code  has  to  look like, anyway. And since most people
tend to use these, there's no point  in  torturing  them  to
always  having  to  change  anything  their editor thinks it
knows better. ;)


[1m3.  Debug Logging[0m


     AdPlug recently offers centralized  debug  log  manage-
ment.  If  you  like  to implement debug logging inside your
code, please follow these guidelines:


     To implement debug logging, [4m#include[24m [4m"debug.h"[24m in  your
code  (this  header  is [1mNOT [22mbeing installed with the rest of
the AdPlug header files into your  standard  include  direc-
tory!  It is only available in AdPlug's src/ subdirectory!).


     [4mdebug.h[24m is C code, so it is useable from both C and C++
sources.   The   only  function  you  have  to  use  is  the
[4mLogWrite(fmt,[24m [4m...)[24m  function.  [4mLogFile()[24m is used  by  AdPlug
internally.  [4mLogWrite()[24m works exactly like [4mprintf()[24m, instead
that it writes to a logfile, rather than on the console.









                             -2-


[1mPlease format your log messages like this:[0m


+o    If your method/function is going to  output  a  lot  of
     debug  info  (i.e.  more  than  one line), please put a
     [4mLogWrite()[24m directly at the beginning of your  function,
     which looks like this:


          LogWrite("*** yourclass::yourmethod(param1,param2) ***\n");



     And  put  the  following  line before every return from
your function:


     LogWrite("--- yourclass::yourmethod ---\n");



     This way, one can easily inspect the logfile  and  know
to  which  function  every  logfile-line  belongs. The '***'
lines mark the start of a function, and the '---' lines mark
the end.


     Please substitute [4mparam*[24m with the corresponding parame-
ter values of your function,  if  that  is  reasonable.  For
example,  it  won't  help much to log a pointer value - just
put something bogus or helpful there, or noting (i.e.   just
a  comma,  so  the logfile reader knows, to which parameters
the other values correspond).  But  logging  the  values  of
passed ints or strings could be very helpful.


+o    If  your  method/function  is  going to output just one
     line, format the line something like this:


          LogWrite("yourclass::yourmethod(param1,param2): your message\n");



     You don't need the '***' and '---'  beginning  and  end
markers then.


+o    For asynchronous threads, there is no way but to prefix
     any line with the function name, because these messages
     will be sprayed throughout the logfile.












                             -3-


[1m4.  Documentation[0m


     AdPlug's  documentation  is  written in ASCII textfiles
and Troff files. This was my own decision, since i  consider
TeX  too bloated. The Troff documentation currently uses the
-ms macro package, as well as the tbl preprocessor. Any cur-
rent  Troff  implementation  should  support that. I use GNU
Troff for typesetting, myself.


     If you would like to add to the existing documentation,
please use the writing style, that's already been used here.


     If you need more info about Troff or need the software,
it is best to go to the official GNU Troff homepage at:


+o    [4mhttp://www.gnu.org/software/groff/[0m








































