From 9020dc00a095952008d4775f5fafc382e85022b9 Mon Sep 17 00:00:00 2001 From: swa Date: Sun, 21 Oct 2001 17:07:21 +0000 Subject: [PATCH] also provide developer and faq docs. --- doc/text/developer-manual.txt | 1203 +++++++++++++++++++++++++++++++++ doc/text/faq.txt | 97 +++ 2 files changed, 1300 insertions(+) create mode 100644 doc/text/developer-manual.txt create mode 100644 doc/text/faq.txt diff --git a/doc/text/developer-manual.txt b/doc/text/developer-manual.txt new file mode 100644 index 00000000..06030c27 --- /dev/null +++ b/doc/text/developer-manual.txt @@ -0,0 +1,1203 @@ + +Junkbuster Developer Manual + + By: Junkbuster Developers + + $Id: developer-manual.sgml,v 1.4 2001/09/23 10:13:48 swa Exp $ + + The developer manual gives the users information on how to help the + developer team. It provides guidance on coding, testing, documentation + and other issues. The Internet Junkbuster is an application that + provides privacy and security to the user of the world wide web. + + You can find the latest version of the user manual at + [1]http://ijbswa.sourceforge.net/developer-manual/. Please see the + Contact section in the user-manual if you want to contact the + developers. + + Feel free to send a note to the developers at + <[2]ijbswa-developers@lists.sourceforge.net>. + _________________________________________________________________ + + Table of Contents + 1. [3]Introduction + 2. [4]Quickstart to Junkbuster Development + 3. [5]Documentation Guidelines + 4. [6]Coding Guidelines + + 4.1. [7]Introduction + 4.2. [8]Using Comments + 4.3. [9]Naming Conventions + 4.4. [10]Using Space + 4.5. [11]Initializing + 4.6. [12]Functions + 4.7. [13]General Coding Practices + 4.8. [14]Addendum: Template for files and function comment + blocks: + + 5. [15]Version Control Guidelines + 6. [16]Testing Guidelines + + 6.1. [17]Testplan for releases + 6.2. [18]Test reports + + 7. [19]Contact the developers + 8. [20]Copyright and History + 9. [21]See also + +1. Introduction + + To be filled. + _________________________________________________________________ + +2. Quickstart to Junkbuster Development + + To be filled. + _________________________________________________________________ + +3. Documentation Guidelines + + All docs should be ... + + * in a format that is widely used. I propose HTML. + * we either + + generate man pages from the documentation (let's _NOT_ write + them manually), or + + we have a man page that points to the documentation (I + propose this option) + * have a consistent layout + * have a link to the latest version of the document (i.e. point to a + URL at sf) + * be consistent with the redirect script (i.e. the junkbuster + program points via the redirect URL at sf to valid end-points in + the document) + * started from scratch but recycle parts from the original + junkbuster documents + _________________________________________________________________ + +4. Coding Guidelines + +4.1. Introduction + + This set of standards is designed to make our lives easier. It is + developed with the simple goal of helping us keep the "new and + improved Junkbusters" consistent and reliable. Thus making maintenance + easier and increasing chances of success of the project. + + And that of course comes back to us as individuals. If we can increase + our development and product efficiencies then we can solve more of the + request for changes/improvements and in general feel good about + ourselves. ;-> + _________________________________________________________________ + +4.2. Using Comments + +4.2.1. Comment, Comment, Comment + + Explanation: + + Comment as much as possible without commenting the obvious. For + example do not comment "aVariable is equal to bVariable". Instead + explain why aVariable should be equal to the bVariable. Just because a + person can read code does not mean they will understand why or what is + being done. A reader may spend a lot more time figuring out what is + going on when a simple comment or explanation would have prevented the + extra research. Please help your brother IJB'ers out! + + The comments will also help justify the intent of the code. If the + comment describes something different than what the code is doing then + maybe a programming error is occurring. + + Example: +/* if page size greater than 1k ... */ +if ( PageLength() > 1024 ) +{ + ... "block" the page up ... +} + +/* if page size is small, send it in blocks */ +if ( PageLength() > 1024 ) +{ + ... "block" the page up ... +} + +This demonstrates 2 cases of "what not to do". The first is a +"syntax comment". The second is a comment that does not fit what +is actually being done. + _________________________________________________________________ + +4.2.2. Use blocks for comments + + Explanation: + + Comments can help or they can clutter. They help when they are + differentiated from the code they describe. One line comments do not + offer effective separation between the comment and the code. Block + identifiers do, by surrounding the code with a clear, definable + pattern. + + Example: +/********************************************************************* + * This will stand out clearly in your code! + *********************************************************************/ +if ( thisVariable == thatVariable ) +{ + DoSomethingVeryImportant(); +} + + +/* unfortunately, this may not */ +if ( thisVariable == thatVariable ) +{ + DoSomethingVeryImportant(); +} + + +if ( thisVariable == thatVariable ) /* this may not either */ +{ + DoSomethingVeryImportant(); +} + + Exception: + + If you are trying to add a small logic comment and do not wish to + "disrubt" the flow of the code, feel free to use a 1 line comment + which is NOT on the same line as the code. + _________________________________________________________________ + +4.2.3. Keep Comments on their own line + + Explanation: + + It goes back to the question of readability. If the comment is on the + same line as the code it will be harder to read than the comment that + is on its own line. + + There are three exceptions to this rule, which should be violated + freely and often: during the definition of variables, at the end of + closing braces, when used to comment parameters. + + Example: +/********************************************************************* + * This will stand out clearly in your code, + * But the second example won't. + *********************************************************************/ +if ( thisVariable == thatVariable ) +{ + DoSomethingVeryImportant(); +} + +if ( thisVariable == thatVariable ) /*can you see me?*/ +{ + DoSomethingVeryImportant(); /*not easily*/ +} + + +/********************************************************************* + * But, the encouraged exceptions: + *********************************************************************/ +int urls_read = 0; /* # of urls read + rejected */ +int urls_rejected = 0; /* # of urls rejected */ + +if ( 1 == X ) +{ + DoSomethingVeryImportant(); +} + + +short DoSomethingVeryImportant( + short firstParam, /* represents something */ + short nextParam /* represents something else */ ) +{ + ...code here... + +} /* -END- DoSomethingVeryImportant */ + _________________________________________________________________ + +4.2.4. Comment each logical step + + Explanation: + + Logical steps should be commented to help others follow the intent of + the written code and comments will make the code more readable. + + If you have 25 lines of code without a comment, you should probably go + back into it to see where you forgot to put one. + + Most "for", "while", "do", etc... loops _probably_ need a comment. + After all, these are usually major logic containers. + _________________________________________________________________ + +4.2.5. Comment All Functions Thoroughly + + Explanation: + + A reader of the code should be able to look at the comments just prior + to the beginning of a function and discern the reason for its + existence and the consequences of using it. The reader should not have + to read through the code to determine if a given function is safe for + a desired use. The proper information thoroughly presented at the + introduction of a function not only saves time for subsequent + maintenance or debugging, it more importantly aids in code reuse by + allowing a user to determine the safety and applicability of any + function for the problem at hand. As a result of such benefits, all + functions should contain the information presented in the addendum + section of this document. + _________________________________________________________________ + +4.2.6. Comment at the end of braces if the content is more than one screen +length + + Explanation: + + Each closing brace should be followed on the same line by a comment + that describes the origination of the brace if the original brace is + off of the screen, or otherwise far away from the closing brace. This + will simplify the debugging, maintenance, and readability of the code. + + As a suggestion , use the following flags to make the comment and its + brace more readable: + + use following a closing brace: } /* -END- if() or while () or etc... + */ + + Example: +if ( 1 == X ) +{ + DoSomethingVeryImportant(); + ...some long list of commands... +} /* -END- if x is 1 */ + +or: + +if ( 1 == X ) +{ + DoSomethingVeryImportant(); + ...some long list of commands... +} /* -END- if ( 1 == X ) */ + _________________________________________________________________ + +4.3. Naming Conventions + +4.3.1. Variable Names + + Explanation: + + Use all lowercase, and seperate words via an underscore ('_'). Do not + start an identifier with an underscore. (ANSI C reserves these for use + by the compiler and system headers.) Do not use identifiers which are + reserved in ANSI C++. (E.g. template, class, true, false, ...). This + is in case we ever decide to port JunkBuster to C++. + + Example: +int ms_iis5_hack = 0; + + Instead of: + +int msiis5hack = 0; int msIis5Hack = 0; + _________________________________________________________________ + +4.3.2. Function Names + + Explanation: + + Use all lowercase, and seperate words via an underscore ('_'). Do not + start an identifier with an underscore. (ANSI C reserves these for use + by the compiler and system headers.) Do not use identifiers which are + reserved in ANSI C++. (E.g. template, class, true, false, ...). This + is in case we ever decide to port JunkBuster to C++. + + Example: +int load_some_file( struct client_state *csp ) + + Instead of: + +int loadsomefile( struct client_state *csp ) +int loadSomeFile( struct client_state *csp ) + _________________________________________________________________ + +4.3.3. Header file prototypes + + Explanation: + + Use a descriptive parameter name in the function prototype in header + files. Use the same parameter name in the header file that you use in + the c file. + + Example: +(.h) extern int load_aclfile( struct client_state *csp ); +(.c) int load_aclfile( struct client_state *csp ) + + Instead of: +(.h) extern int load_aclfile( struct client_state * ); or +(.h) extern int load_aclfile(); +(.c) int load_aclfile( struct client_state *csp ) + _________________________________________________________________ + +4.3.4. Enumerations, and #defines + + Explanation: + + Use all capital letters, with underscores between words. Do not start + an identifier with an underscore. (ANSI C reserves these for use by + the compiler and system headers.) + + Example: +(enumeration) : enum Boolean { FALSE, TRUE }; +(#define) : #define DEFAULT_SIZE 100; + + Note: We have a standard naming scheme for #defines that toggle a + feature in the preprocessor: FEATURE_>, where > is a short (preferably + 1 or 2 word) description. + + Example: +#define FEATURE_FORCE 1 + +#ifdef FEATURE_FORCE +#define FORCE_PREFIX blah +#endif /* def FEATURE_FORCE */ + _________________________________________________________________ + +4.3.5. Constants + + Explanation: + + Spell common words out entirely (do not remove vowels). + + Use only widely-known domain acronyms and abbreviations. Capitalize + all letters of an acronym. + + Use underscore (_) to separate adjacent acronyms and abbreviations. + Never terminate a name with an underscore. + + Example: +#define USE_IMAGE_LIST 1 + + Instead of: + +#define USE_IMG_LST 1 or +#define _USE_IMAGE_LIST 1 or +#define USE_IMAGE_LIST_ 1 or +#define use_image_list 1 or +#define UseImageList 1 + _________________________________________________________________ + +4.4. Using Space + +4.4.1. Put braces on a line by themselves. + + Explanation: + + The brace needs to be on a line all by itself, not at the end of the + statement. Curly braces should line up with the construct that they're + associated with. This practice makes it easier to identify the opening + and closing braces for a block. + + Example: +if ( this == that ) +{ + ... +} + + Instead of: + + if ( this == that ) { ... } + + or + + if ( this == that ) { ... } + + Note: In the special case that the if-statement is inside a loop, and + it is trivial, i.e. it tests for a condidtion that is obvious from the + purpose of the block, one-liners as above may optically preserve the + loop structure and make it easier to read. + + Status: developer-discrection. + + Example exception: +while ( more lines are read ) +{ + /* Please document what is/is not a comment line here */ + if ( it's a comment ) continue; + + do_something( line ); +} + _________________________________________________________________ + +4.4.2. ALL control statements should have a block + + Explanation: + + Using braces to make a block will make your code more readable and + less prone to error. All control statements should have a block + defined. + + Example: +if ( this == that ) +{ + DoSomething(); + DoSomethingElse(); +} + + Instead of: + + if ( this == that ) DoSomething(); DoSomethingElse(); + + or + + if ( this == that ) DoSomething(); + + Note: The first example in "Instead of" will execute in a manner other + than that which the developer desired (per indentation). Using code + braces would have prevented this "feature". The "explanation" and + "exception" from the point above also applies. + _________________________________________________________________ + +4.4.3. Do not belabor/blow-up boolean expressions + + Example: +structure->flag = ( condition ); + + Instead of: + + if ( condition ) { structure->flag = 1; } else { structure->flag = 0; + } + + Note: The former is readable and consice. The later is wordy and + inefficient. Please assume that any developer new to the project has + at least a "good" knowledge of C/C++. (Hope I do not offend by that + last comment ... 8-) + _________________________________________________________________ + +4.4.4. Use white space freely because it is free + + Explanation: + + Make it readable. The notable exception to using white space freely is + listed in the next guideline. + + Example: +int firstValue = 0; +int someValue = 0; +int anotherValue = 0; +int thisVariable = 0; + +if ( thisVariable == thatVariable ) + +firstValue = oldValue + ( ( someValue - anotherValue ) - whatever ) + _________________________________________________________________ + +4.4.5. Don't use white space around structure operators + + Explanation: + + - structure pointer operator ( "->" ) - member operator ( "." ) - + functions and parentheses + + It is a general coding practice to put pointers, references, and + function parentheses next to names. With spaces, the connection + between the object and variable/function name is not as clear. + + Example: +aStruct->aMember; +aStruct.aMember; +FunctionName(); + + Instead of: aStruct -> aMember; aStruct . aMember; FunctionName (); + _________________________________________________________________ + +4.4.6. Make the last brace of a function stand out + + Example: +int function1( ... ) +{ + ...code... + return( retCode ); + +} /* -END- function1 */ + + +int function2( ... ) +{ +} /* -END- function2 */ + + Instead of: + + int function1( ... ) { ...code... return( retCode ); } int function2( + ... ) { } + + Note: Use 1 blank line before the closing brace and 2 lines + afterwards. This makes the end of function standout to the most casual + viewer. Although function comments help seperate functions, this is + still a good coding practice. In fact, I follow these rules when using + blocks in "for", "while", "do" loops, and long if {} statements too. + After all whitespace is free! + + Status: developer-discrection on the number of blank lines. Enforced + is the end of function comments. + _________________________________________________________________ + +4.4.7. Use 3 character indentions + + Explanation: + + If some use 8 character TABs and some use 3 character TABs, the code + can look *very* ragged. So use 3 character indentions only. If you + like to use TABs, pass your code through a filter such as "expand -t3" + before checking in your code. + + Example: +static const char * const url_code_map[256] = +{ + NULL, ... +}; + + +int function1( ... ) +{ + if ( 1 ) + { + return( ALWAYS_TRUE ); + } + else + { + return( HOW_DID_YOU_GET_HERE ); + } + + return( NEVER_GETS_HERE ); + +} + _________________________________________________________________ + +4.5. Initializing + +4.5.1. Initialize all variables + + Explanation: + + Do not assume that the variables declared will not be used until after + they have been assigned a value somewhere else in the code. Remove the + chance of accidentally using an unassigned variable. + + Example: +short anShort = 0; +float aFloat = 0; +struct *ptr = NULL; + + Note: It is much easier to debug a SIGSEGV if the message says you are + trying to access memory address 00000000 and not 129FA012; or + arrayPtr[20] causes a SIGSEV vs. arrayPtr[0]. + + Status: developer-discrection if and only if the variable is assigned + a value "shortly after" declaration. + _________________________________________________________________ + +4.6. Functions + +4.6.1. Name functions that return a boolean as a question. + + Explanation: + + Value should be phrased as a question that would logically be answered + as a true or false statement + + Example: +ShouldWeBlockThis(); +ContainsAnImage(); +IsWebPageBlank(); + _________________________________________________________________ + +4.6.2. Always specify a return type for a function. + + Explanation: + + The default return for a function is an int. To avoid ambiguity, + create a return for a function when the return has a purpose, and + create a void return type if the function does not need to return + anything. + _________________________________________________________________ + +4.6.3. Minimize function calls when iterating by using variables + + Explanation: + + It is easy to write the following code, and a clear argument can be + made that the code is easy to understand: + + Example: +for ( size_t cnt = 0; cnt < blockListLength(); cnt ++ ) +{ + .... +} + + Note: Unfortunately, this makes a function call for each and every + iteration. This increases the overhead in the program, because the + compiler has to look up the function each time, call it, and return a + value. Depending on what occurs in the blockListLength() call, it + might even be creating and destroying structures with each iteration, + even though in each case it is comparing "cnt" to the same value, over + and over. Remember too - even a call to blockListLength() is a + function call, with the same overhead. + + Instead of using a function call during the iterations, assign the + value to a variable, and evaluate using the variable. + + Example: +size_t len = blockListLength(); + +for ( size_t cnt = 0; cnt < len; cnt ++ ) +{ + .... +} + + Exceptions: if the value of blockListLength() *may* change or could + *potentially* change, then you must code the function call in the + for/while loop. + _________________________________________________________________ + +4.6.4. Pass and Return by Const Reference + + Explanation: + + This allows a developer to define a const pointer and call your + function. If your function does not have the const keyword, we may not + be able to use your function. Consider strcmp, if it were defined as: + extern int strcmp( char *s1, char *s2 ); + + I could then not use it to compare argv's in main: int main( int argc, + const char *argv[] ) { strcmp( argv[0], "junkbusters" ); } + + Both these pointers are *const*! If the c runtime library maintainers + do it, we should too. + _________________________________________________________________ + +4.6.5. Pass and Return by Value + + Explanation: + + Most structures cannot fit onto a normal stack entry (i.e. they are + not 4 bytes or less). Aka, a function declaration like: int + load_aclfile( struct client_state csp ) + + would not work. So, to be consistent, we should declare all prototypes + with "pass by value": int load_aclfile( struct client_state *csp ) + _________________________________________________________________ + +4.6.6. Names of include files + + Explanation: + + Your include statements should contain the file name without a path. + The path should be listed in the Makefile, using -I as processor + directive to search the indicated paths. An exception to this would be + for some proprietary software that utilizes a partial path to + distinguish their header files from system or other header files. + + Example: +#include /* This is not a local include */ +#include "config.h" /* This IS a local include */ + + Exception: + +/* This is not a local include, but requires a path element. */ +#include + + Note: Please! do not add "-I." to the Makefile without a _very_ good + reason. This duplicates the #include "file.h" behaviour. + _________________________________________________________________ + +4.6.7. Provide multiple inclusion protection + + Explanation: + + Prevents compiler and linker errors resulting from redefinition of + items. + + Wrap each header file with the following syntax to prevent multiple + inclusions of the file. Of course, replace PROJECT_H with your file + name, with "." Changed to "_", and make it uppercase. + + Example: +#ifndef PROJECT_H_INCLUDED +#define PROJECT_H_INCLUDED + ... +#endif /* ndef PROJECT_H_INCLUDED */ + _________________________________________________________________ + +4.6.8. Use `extern "C"` when appropriate + + Explanation: + + If our headers are included from C++, they must declare our functions + as `extern "C"`. This has no cost in C, but increases the potential + re-usability of our code. + + Example: +#ifdef __cplusplus +extern "C" +{ +#endif /* def __cplusplus */ + +... function definitions here ... + +#ifdef __cplusplus +} +#endif /* def __cplusplus */ + _________________________________________________________________ + +4.6.9. Where Possible, Use Forward Struct Declaration Instead of Includes + + Explanation: + + Useful in headers that include pointers to other struct's. + Modifications to excess header files may cause needless compiles. + + Example: +/********************************************************************* + * We're avoiding an include statement here! + *********************************************************************/ +struct file_list; +extern file_list *xyz; + + Note: If you declare "file_list xyz;" (without the pointer), then + including the proper header file is necessary. If you only want to + prototype a pointer, however, the header file is unneccessary. + + Status: Use with discrection. + _________________________________________________________________ + +4.7. General Coding Practices + +4.7.1. Turn on warnings + + Explanation + + Compiler warnings are meant to help you find bugs. You should turn on + as many as possible. With GCC, the switch is "-Wall". Try and fix as + many warnings as possible. + _________________________________________________________________ + +4.7.2. Provide a default case for all switch statements + + Explanation: + + What you think is guaranteed is never really guaranteed. The value + that you don't think you need to check is the one that someday will be + passed. So, to protect yourself from the unknown, always have a + default step in a switch statement. + + Example: +switch( hash_string( cmd ) ) +{ + case hash_actions_file : + ... code ... + break; + + case hash_confdir : + ... code ... + break; + + default : + log_error( ... ); + ... anomly code goes here ... + continue; / break; / exit( 1 ); / etc ... + +} /* end switch( hash_string( cmd ) ) */ + + Note: If you already have a default condition, you are obviously + exempt from this point. Of note, most of the WIN32 code calls + `DefWindowProc' after the switch statement. This API call *should* be + included in a default statement. + + Another Note: This is not so much a readability issue as a robust + programming issue. The "anomly code goes here" may be no more than a + print to the STDERR stream (as in load_config). Or it may really be an + ABEND condition. + + Status: Programmer discretion is advised. + _________________________________________________________________ + +4.7.3. Try to avoid falling through cases in a switch statement. + + Explanation: + + In general, you will want to have a 'break' statement within each + 'case' of a switch statement. This allows for the code to be more + readable and understandable, and furthermore can prevent unwanted + surprises if someone else later gets creative and moves the code + around. + + The language allows you to plan the fall through from one case + statement to another simply by omitting the break statement within the + case statement. This feature does have benefits, but should only be + used in rare cases. In general, use a break statement for each case + statement. + + If you choose to allow fall through, you should comment both the fact + of the fall through and reason why you felt it was necessary. + _________________________________________________________________ + +4.7.4. Use 'long' or 'short' Instead of 'int' + + Explanation: + + On 32-bit platforms, int usually has the range of long. On 16-bit + platforms, int has the range of short. + + Status: open-to-debate. In the case of most FSF projects (including + X/GNU-Emacs), there are typedefs to int4, int8, int16, (or equivalence + ... I forget the exact typedefs now). Should we add these to IJB now + that we have a "configure" script? + _________________________________________________________________ + +4.7.5. Don't mix size_t and other types + + Explanation: + + The type of size_t varies across platforms. Do not make assumptions + about whether it is signed or unsigned, or about how long it is. Do + not compare a size_t against another variable of a different type (or + even against a constant) without casting one of the values. Try to + avoid using size_t if you can. + _________________________________________________________________ + +4.7.6. Declare each variable and struct on its own line. + + Explanation: + + It can be tempting to declare a series of variables all on one line. + Don't. + + Example: +long a = 0; +long b = 0; +long c = 0; + + Instead of: + + long a, b, c; + + Explanation: - there is more room for comments on the individual + variables - easier to add new variables without messing up the + original ones - when searching on a variable to find its type, there + is less clutter to "visually" eliminate + + Exceptions: when you want to declare a bunch of loop variables or + other trivial variables; feel free to declare them on 1 line. You + should, although, provide a good comment on their functions. + + Status: developer-discrection. + _________________________________________________________________ + +4.7.7. Use malloc/zalloc sparingly + + Explanation: + + Create a local stuct (on the stack) if the variable will live and die + within the context of one function call. + + Only "malloc" a struct (on the heap) if the variable's life will + extend beyond the context of one function call. + + Example: +If a function creates a struct and stores a pointer to it in a +list, then it should definately be allocated via `malloc'. + _________________________________________________________________ + +4.7.8. The Programmer Who Uses 'malloc' is Responsible for Ensuring 'free' + + Explanation: + + If you have to "malloc" an instance, you are responsible for insuring + that the instance is `free'd, even if the deallocation event falls + within some other programmer's code. You are also responsible for + ensuring that deletion is timely (i.e. not too soon, not too late). + This is known as "low-coupling" and is a "good thing (tm)". You may + need to offer a free/unload/destuctor type function to accomodate + this. + + Example: +int load_re_filterfile( struct client_state *csp ) { ... } +static void unload_re_filterfile( void *f ) { ... } + + Exceptions: + + The developer cannot be expected to provide `free'ing functions for C + run-time library functions ... such as `strdup'. + + Status: developer-discrection. The "main" use of this standard is for + allocating and freeing data structures (complex or nested). + _________________________________________________________________ + +4.7.9. Add loaders to the `file_list' structure and in order + + Explanation: + + I have ordered all of the "blocker" file code to be in alpha order. It + is easier to add/read new blockers when you expect a certain order. + + Note: It may appear that the alpha order is broken in places by POPUP + tests coming before PCRS tests. But since POPUPs can also be referred + to as KILLPOPUPs, it is clear that it should come first. + _________________________________________________________________ + +4.7.10. "Uncertain" new code and/or changes to exitinst code, use FIXME + + Explanation: + + If you have enough confidence in new code or confidence in your + changes, but are not *quite* sure of the reprocussions, add this: + + /* FIXME: this code has a logic error on platform XYZ, * attempthing + to fix */ #ifdef PLATFORM ...changed code here... #endif + + or: + + /* FIXME: I think the original author really meant this... */ + ...changed code here... + + or: + + /* FIXME: new code that *may* break something else... */ ...new code + here... + + Note: If you make it clear that this may or may not be a "good thing + (tm)", it will be easier to identify and include in the project (or + conversly exclude from the project). + _________________________________________________________________ + +4.8. Addendum: Template for files and function comment blocks: + + Example for file comments: +const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.4 2001/09/23 10:13: +48 swa Exp $"; +/********************************************************************* + * + * File : $Source$ + * + * Purpose : (Fill me in with a good description!) + * + * Copyright : Written by and Copyright (C) 2001 the SourceForge + * IJBSWA team. http://ijbswa.sourceforge.net + * + * Based on the Internet Junkbuster originally written + * by and Copyright (C) 1997 Anonymous Coders and + * Junkbusters Corporation. http://www.junkbusters.com + * + * This program is free software; you can redistribute it + * and/or modify it under the terms of the GNU General + * Public License as published by the Free Software + * Foundation; either version 2 of the License, or (at + * your option) any later version. + * + * This program is distributed in the hope that it will + * be useful, but WITHOUT ANY WARRANTY; without even the + * implied warranty of MERCHANTABILITY or FITNESS FOR A + * PARTICULAR PURPOSE. See the GNU General Public + * License for more details. + * + * The GNU General Public License should be included with + * this file. If not, you can view it at + * http://www.gnu.org/copyleft/gpl.html + * or write to the Free Software Foundation, Inc., 59 + * Temple Place - Suite 330, Boston, MA 02111-1307, USA. + * + * Revisions : + * $Log$ + * + *********************************************************************/ + + +#include "config.h" + + ...necessary include files for us to do our work... + +const char FILENAME_h_rcs[] = FILENAME_H_VERSION; + + Note: This declares the rcs variables that should be added to the + "show-proxy-args" page. If this is a brand new creation by you, you + are free to change the "Copyright" section to represent the rights you + wish to maintain. + + Note: The formfeed character that is present right after the comment + flower box is handy for (X|GNU)Emacs users to skip the verbige and get + to the heart of the code (via `forward-page' and `backward-page'). + Please include it if you can. + + Example for file header comments: +#ifndef _FILENAME_H +#define _FILENAME_H +#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 1.4 2001/09/23 10:13:4 +8 swa Exp $" +/********************************************************************* + * + * File : $Source$ + * + * Purpose : (Fill me in with a good description!) + * + * Copyright : Written by and Copyright (C) 2001 the SourceForge + * IJBSWA team. http://ijbswa.sourceforge.net + * + * Based on the Internet Junkbuster originally written + * by and Copyright (C) 1997 Anonymous Coders and + * Junkbusters Corporation. http://www.junkbusters.com + * + * This program is free software; you can redistribute it + * and/or modify it under the terms of the GNU General + * Public License as published by the Free Software + * Foundation; either version 2 of the License, or (at + * your option) any later version. + * + * This program is distributed in the hope that it will + * be useful, but WITHOUT ANY WARRANTY; without even the + * implied warranty of MERCHANTABILITY or FITNESS FOR A + * PARTICULAR PURPOSE. See the GNU General Public + * License for more details. + * + * The GNU General Public License should be included with + * this file. If not, you can view it at + * http://www.gnu.org/copyleft/gpl.html + * or write to the Free Software Foundation, Inc., 59 + * Temple Place - Suite 330, Boston, MA 02111-1307, USA. + * + * Revisions : + * $Log$ + * + *********************************************************************/ + + +#include "project.h" + +#ifdef __cplusplus +extern "C" { +#endif + + ... function headers here ... + + +/* Revision control strings from this header and associated .c file */ +extern const char FILENAME_rcs[]; +extern const char FILENAME_h_rcs[]; + + +#ifdef __cplusplus +} /* extern "C" */ +#endif + +#endif /* ndef _FILENAME_H */ + +/* + Local Variables: + tab-width: 3 + end: +*/ + + Example for function comments: +/********************************************************************* + * + * Function : FUNCTION_NAME + * + * Description : (Fill me in with a good description!) + * + * Parameters : + * 1 : param1 = pointer to an important thing + * 2 : x = pointer to something else + * + * Returns : 0 => Ok, everything else is an error. + * + *********************************************************************/ +int FUNCTION_NAME( void *param1, const char *x ) +{ + ... + return( 0 ); + +} + + Note: If we all follow this practice, we should be able to parse our + code to create a "self-documenting" web page. + _________________________________________________________________ + +5. Version Control Guidelines + + To be filled. note on cvs comments. don't comment what you did, + comment why you did it. + _________________________________________________________________ + +6. Testing Guidelines + + To be filled. + _________________________________________________________________ + +6.1. Testplan for releases + + Explain release numbers. major, minor. developer releases. etc. + + 1. Remove any existing rpm with rpm -e + 2. Remove any file that was left over. This includes (but is not + limited to) + + /var/log/junkbuster + + /etc/junkbuster + + /usr/sbin/junkbuster + + /etc/init.d/junkbuster + + /usr/doc/junkbuster* + 3. Install the rpm. Any error messages? + 4. start,stop,status junkbuster with the specific script (e.g. + /etc/rc.d/init/junkbuster stop). Reboot your machine. Does + autostart work? + 5. Start browsing. Does the junkbuster work? Logfile written? + 6. Remove the rpm. Any error messages? All files removed? + _________________________________________________________________ + +6.2. Test reports + + Please submit test reports only with the [22]test form at sourceforge. + Three simple steps: + + * Select category: the distribution you test on. + * Select group: the version of Junkbuster that we are about to + release. + * Fill the Summary and Detailed Description with something + intelligent (keep it short and precise). + + Do not mail to the mailinglist (we cannot keep track on issues there). + _________________________________________________________________ + +7. Contact the developers + + Please see the user manual for information on how to contact the + developers. + _________________________________________________________________ + +8. Copyright and History + + Please see the user manual for information on Copyright and History. + _________________________________________________________________ + +9. See also + + Please see the user manual for information on references. + +References + + 1. http://ijbswa.sourceforge.net/developer-manual/ + 2. mailto:ijbswa-developers@lists.sourceforge.net + 3. file://localhost/home/swa/sf/current/doc/source/tmp.html#INTRODUCTION + 4. file://localhost/home/swa/sf/current/doc/source/tmp.html#QUICKSTART + 5. file://localhost/home/swa/sf/current/doc/source/tmp.html#DOCUMENTATION + 6. file://localhost/home/swa/sf/current/doc/source/tmp.html#CODING + 7. file://localhost/home/swa/sf/current/doc/source/tmp.html#S1 + 8. file://localhost/home/swa/sf/current/doc/source/tmp.html#S2 + 9. file://localhost/home/swa/sf/current/doc/source/tmp.html#S9 + 10. file://localhost/home/swa/sf/current/doc/source/tmp.html#S15 + 11. file://localhost/home/swa/sf/current/doc/source/tmp.html#S23 + 12. file://localhost/home/swa/sf/current/doc/source/tmp.html#S25 + 13. file://localhost/home/swa/sf/current/doc/source/tmp.html#S35 + 14. file://localhost/home/swa/sf/current/doc/source/tmp.html#S46 + 15. file://localhost/home/swa/sf/current/doc/source/tmp.html#CVS + 16. file://localhost/home/swa/sf/current/doc/source/tmp.html#TESTING + 17. file://localhost/home/swa/sf/current/doc/source/tmp.html#TESTING-PLAN + 18. file://localhost/home/swa/sf/current/doc/source/tmp.html#TESTING-REPORT + 19. file://localhost/home/swa/sf/current/doc/source/tmp.html#CONTACT + 20. file://localhost/home/swa/sf/current/doc/source/tmp.html#COPYRIGHT + 21. file://localhost/home/swa/sf/current/doc/source/tmp.html#SEEALSO + 22. http://sourceforge.net/tracker/?func=add&group_id=11118&atid=395005 diff --git a/doc/text/faq.txt b/doc/text/faq.txt new file mode 100644 index 00000000..14337bcc --- /dev/null +++ b/doc/text/faq.txt @@ -0,0 +1,97 @@ + +Junkbuster Frequently Asked Questions + + By: Junkbuster Developers + + $Id: faq.sgml,v 1.3 2001/09/23 10:13:48 swa Exp $ + + The FAQ document gives users and developers alike answers to + frequently asked questions about the Internet Junkbuster. The Internet + Junkbuster is an application that provides privacy and security to the + user of the world wide web. + + You can find the latest version of the document at + [1]http://ijbswa.sourceforge.net/faq/. Please see the Contact section + in the user-manual if you want to contact the developers. + + Feel free to send a note to the developers at + <[2]ijbswa-developers@lists.sourceforge.net>. + _________________________________________________________________ + + Table of Contents + 1. [3]Introduction + 2. [4]Frequently Asked Questions + + 2.1. [5]Installation + 2.2. [6]Configuration + 2.3. [7]Misc + + 3. [8]Contact the developers + 4. [9]Copyright and History + 5. [10]See also + +1. Introduction + + To be filled. + _________________________________________________________________ + +2. Frequently Asked Questions + +2.1. Installation + + To be done later. + _________________________________________________________________ + +2.2. Configuration + +2.2.1. How can I make my Yahoo account work? + _________________________________________________________________ + +2.2.2. How can I make my Hotmail account work? + _________________________________________________________________ + +2.2.3. How can I make my GMX account work? + _________________________________________________________________ + +2.3. Misc + +2.3.1. How can I hide my IP address? + + You cannot hide your IP address with Junkbuster. + _________________________________________________________________ + +2.3.2. What is the imagefile (simage.ini, etc.) for? + + Anytime the Junkbuster determines (with the help of the blocklist) + that a URL contains an advertisement, it has to decide whether this + advertisement is an image or not. The Junkbuster uses the imagefile + for that purpose.. + _________________________________________________________________ + +3. Contact the developers + + Please see the user manual for information on how to contact the + developers. + _________________________________________________________________ + +4. Copyright and History + + Please see the user manual for information on Copyright and History. + _________________________________________________________________ + +5. See also + + Please see the user manual for information on references. + +References + + 1. http://ijbswa.sourceforge.net/faq/ + 2. mailto:ijbswa-developers@lists.sourceforge.net + 3. file://localhost/home/swa/sf/current/doc/source/tmp.html#INTRODUCTION + 4. file://localhost/home/swa/sf/current/doc/source/tmp.html#QUESTIONS + 5. file://localhost/home/swa/sf/current/doc/source/tmp.html#INSTALLATION + 6. file://localhost/home/swa/sf/current/doc/source/tmp.html#CONFIGURATION + 7. file://localhost/home/swa/sf/current/doc/source/tmp.html#MISC + 8. file://localhost/home/swa/sf/current/doc/source/tmp.html#CONTACT + 9. file://localhost/home/swa/sf/current/doc/source/tmp.html#COPYRIGHT + 10. file://localhost/home/swa/sf/current/doc/source/tmp.html#SEEALSO -- 2.39.2