X-Git-Url: http://git.madism.org/?p=apps%2Fmadmutt.git;a=blobdiff_plain;f=legacy%2Fdoc%2Fdevel-notes.txt;fp=legacy%2Fdoc%2Fdevel-notes.txt;h=18b0b73facfaa87140a56e492254e0278127c374;hp=0000000000000000000000000000000000000000;hb=3ad8157bbbc6b9fae1c3252aad1c07fcccd92004;hpb=2fea7732a573b94a4d5dcf7e641ef067472e9cab diff --git a/legacy/doc/devel-notes.txt b/legacy/doc/devel-notes.txt new file mode 100644 index 0000000..18b0b73 --- /dev/null +++ b/legacy/doc/devel-notes.txt @@ -0,0 +1,197 @@ +Required tools +-------------- + +If you are planning to hack on Madmutt, please subscribe to the +Madmutt-devel mailinglist (Madmutt-deve-l@lists.berlios.de). +Announcements about recent development +versions go to that mailing list, as go technical discussions and +patches. + +You'll need several GNU development utilities for working on Madmutt: + +- automake + +- autoconf + +- autoheader + +- The i18n stuff requires GNU gettext. See intl/VERSION for the + version we are currently relying on. Please note that using + gettext-0.10 will most probably not work - get the latest test + release from alpha.gnu.org, it's the recommended version of + gettext anyway. + + If you are experiencing problems with unknown "dcgettext" symbols, + the autoconf/automake macros from your gettext package are broken. + Apply the following patch to that macro file (usually found under + /usr/share/aclocal/gettext.m4): + +--- gettext.m4.bak Thu Jul 2 18:46:08 1998 ++++ gettext.m4 Mon Oct 5 23:32:54 1998 +@@ -46,12 +46,13 @@ + + if test "$gt_cv_func_gettext_libc" != "yes"; then + AC_CHECK_LIB(intl, bindtextdomain, +- [AC_CACHE_CHECK([for gettext in libintl], +- gt_cv_func_gettext_libintl, +- [AC_CHECK_LIB(intl, gettext, +- gt_cv_func_gettext_libintl=yes, +- gt_cv_func_gettext_libintl=no)], ++ [AC_CHECK_LIB(intl, gettext, ++ gt_cv_func_gettext_libintl=yes, + gt_cv_func_gettext_libintl=no)]) ++ fi ++ ++ if test "$gt_cv_func_gettext_libintl" = "yes" ; then ++ LIBS="-lintl $LIBS" + fi + + if test "$gt_cv_func_gettext_libc" = "yes" \ + + +- GNU make may be needed for the dependency tricks + + +Getting started from SVN +------------------------ + +Once you've checked out a copy of the source from SVN from +svn.berlios.de/svnroot/repos/Madmutt , you'll need to run the script +called 'autogen.sh' that is in the root directory. The script does all the +automake/autoconf magic that needs to be done with a fresh checkout. If +all steps succeed, you'll have a configure script to start off with. + + +A word about warnings +--------------------- + +Madmutt's default build process sets some pretty restrictive compiler +flags which may lead to lots of warnings. Generally, warnings are +something which should be eliminated. + +Nevertheless, the code in intl/ is said to generate some warnings with +the compiler settings we usually rely upon. This code is not +maintained by the Madmutt developpers, so please redirect any comments to +the GNU gettext library's developpers. + + +Style Guide +----------- + +- global functions outside the library directory should have the prefix + "mutt_". All other functions should be declared "static". All global + functions defined within the library directory should have the the + prefix according to their source file, i.e. "str_" for everything in + lib/str.[ch] etc. + +- avoid global vars where possible. If one is required, + try to contain it to a single source file and declare it + "static". Global vars should have the first letter of + each word capitilized, and no underscores should be used + (e.g., MailGid, LastFolder, MailDir). + +- re-use code as much as possible. There are a lot of + "library" functions. One of the biggest causes of bloat + in ELM and PINE is the tremendous duplication of code... + Help keep Mutt small! + +- When adding new options, make the old behaviour the default. Also, + add them to UPGRADING in the top-level source directory. + +- try to keep Madmutt as portable as possible. + +Documentation +------------- + +Please document your changes. Note that there are several places +where you may have to add documentation: + +- doc/manual.sgml.{head,tail} contain The Manual. + +- doc/muttngrc.man.{head,tail} contain an abriged version of The + Manual in nroff format (see man(7)), which deals with + configuration file commands. + +Configuration _variables_ are documented directly in init.h. Note +that this includes documentation for possibly added format flags! + +When adding variables which depend on system-functionality and/or +./configure switches, you have to add additional "availability" +information to init.h to avoid confusion in the manual. Please see +init.h for examples. + +The parts of The Manual and the muttngrc manual page dealing with +these variables, and the global Muttrc, are generated automatically +from that documentation. To start this process, type "make +update-doc" in the top-level source directory. + +Note that you may have to update the makedoc utility (makedoc.c) +when adding new data types to init.h. + +More precisely, variable name, type, and default value are directly +extracted from the initializer for the MuttVars array. Documentation +is exepected in special comments which _follow_ the initializer. +For a line to be included with the documentation, it must (after, +possibly, some white space) begin with with either "/**" or "**". +Any following white space is ignored. The rest of the line is +expected to be plain text, with some formatting instructions roughly +similar to [ntg]roff: + + - \fI switches to italics + + - \fB switches to boldface + + - \fT switches to typewriter (only for SGML and ignored otherwise) + + - \fP switches to normal display + + - \(as can be used to represent an asterisk (*). This is intended + to help avoiding character sequences such as /* or */ inside + comments. + + - \(rs can be used to represent a backslash (\). This is intended + to help avoiding poblems when trying to represent any of the \ + sequences used by makedoc. + + - .dl on a line starts a "definition list" environment (name taken + from HTML) where terms and definitions alternate. + + - .dt marks a term in a definition list. + + - .dd marks a definition in a definition list. + + - .de on a line finishes a definition list environment. + + - .ts on a line starts a "verbose tscreen" environment (name taken from + SGML). Please try to keep lines inside such an environment + short; a length of abut 40 characters should be ok. This is + necessary to avoid a really bad-looking muttngrc (5) manual page. + + - .te on a line finishes this environment. + + - .pp on a line starts a paragraph. + + - $word will be converted to a reference to word, where appropriate. + Note that $$word is possible as well. + Use $$$ to get a literal $ without making a reference. + + - '. ' in the beginning of a line expands to two space characters. + This is used to protect indentations in tables. + +Do _not_ use any other SGML or nroff formatting instructions here! + + +String comparison +----------------- + +A word of warning about string comparisons: Since Madmutt may run in a +huge variety of locales, case-insensitive string comparisons and +case conversions may be dangerous. For instance, in iso-8859-9, +tolower('I') is DIFFERENT from 'i' - it's indeed the Turkish dotless +lowercase i. + +For this reason, always use the ascii_* functions defined in ascii.h +and implemented in ascii.c when comparing or handling strings which +are defined as us-ascii. This concerns lots of text-based +protocols, message header tags, character set names, domain names, +e-mail addresses, etc.