Date: Thu, 01 May 2003 19:20:22 +0300 From: "Eli Zaretskii" Sender: halo1 AT zahav DOT net DOT il To: djgpp-workers AT delorie DOT com Message-Id: <7458-Thu01May2003192021+0300-eliz@elta.co.il> X-Mailer: emacs 21.3.50 (via feedmail 8 I) and Blat ver 1.8.9 In-reply-to: <3EB08219.3D55D32A@yahoo.com> (message from CBFalconer on Wed, 30 Apr 2003 22:10:33 -0400) Subject: Re: nmalloc documentation revisions References: <3EAF5020 DOT 9E3C6C9A AT yahoo DOT com> <7458-Wed30Apr2003210444+0300-eliz AT elta DOT co DOT il> <3EB08219 DOT 3D55D32A AT yahoo DOT com> Reply-To: djgpp-workers AT delorie DOT com Errors-To: nobody AT delorie DOT com X-Mailing-List: djgpp-workers AT delorie DOT com X-Unsubscribes-To: listserv AT delorie DOT com Precedence: bulk > Date: Wed, 30 Apr 2003 22:10:33 -0400 > From: CBFalconer > > > > Also, please produce the diffs like this: > > > > diff -c malloc.txh nmalloc.txh > > > > Note the "-c" switch--it's very important. > > Sigh. I guess I have been too used to being chief honcho :-) Try > this. Thanks. Here are my comments: > ! The size of the currently available top portion of the memory > ! assigned by sbrk. Sometimes known as 'slop'. Please change the last sentence into this: Sometimes known as @dfn{slop}. (In general, whenever you introduce some new term, it is advisable to put it into @dfn{}. That causes the term to be typeset in a special typeface which makes it stand out. > ! @table @asis > @item Level 0 > ! The memory allocation functions behave as they do if > ! @code{malloc_debug} was never called. Only passive checks are > ! allowed, including malloc_verify, mallocmap, and malldbgdumpfile Please put all function names, such as malloc_verify, malldbgdumpfile, etc., in @code{}. > ! (to set the output file). In particular mallsethook() is Please don't append "()" to a name of a function to signal that it's a function; instead, say "@code{mallsethook}". "mallsethook()" looks like a call to a function with no arguments, which is not what you meant here. > ! This function prints a map of the heap storage to the selected > ! dumpfile. (See malldbgdumpfile). A cross-reference to another function's description is written like this: (@xref{malldbgdumpfile}.) @xref takes care of producing the leading "See " string in any format that needs it. It also sets up a hypertext link to the appropriate node of the manual, unlike the plain text you used. > ! #include /* on non-DJGPP systems */ > > ! M_HOOKFN mallsethook(enum m_hook_kind which, > ! M_HOOKFN newhook); > @end example > > @subheading Description > > ! These hooks are provided for building custom @code{malloc} > ! debugging packages. The original text said "These hooks" because there was a list of hooks before that. In your modified version, there's no list, so "These" looks awkward. I'd suggest to change the text to say something like this: Several hooks are provided for building custom ... > Each callback is only called if it > ! is non- AT code{NULL}; by default, all of them are initialized to a > @code{NULL} value. Is the above still true in your implementation? > + The actual hook to be set is described by the following > + constants, enumerated in stdlib.h: > + > + malloc_HK = 0 on entry to malloc > + malloc_fail_HK when malloc fails > + free_HK on entry to free > + free_null_HK when free is called with a NULL pointer > + realloc_HK on entry to realloc > + realloc_exit_HK when realloc exits. > + HKCOUNT The first invalid value for a hook descriptor. This will produce badly formatted output, since both `makeinfo' and TeX collapse multiple whitespace characters and refill text. If you want the spaces to be preserved, surround this block with @example DOT DOT AT end example. Better yet, use a @table, like this: @table @code{} @item malloc_HK on entry to malloc @item malloc_fail_HK when malloc fails @item free_HK on entry to free @item free_null_HK when free is called with a NULL pointer @item realloc_HK on entry to realloc @item realloc_exit_HK when realloc exits @item HKCOUNT @end @table > + and each ``callback'' function is described by: > + > + typedef void (*M_HOOKFN)(size_t sz, void *ptr); > + Any block of code should be surrounded by @example DOT DOT AT end example. > + in stdlib.h. File names, such as `stdlib.h', should be in @file{}. Also, whenever a line that starts a paragraph, like the one above, is a continuation of the last line of the previous paragraph, precede it with @noindent, to prevent `makeinfo' and TeX from indenting the line. So the above fragment should be written thusly: and each ``callback'' function is described by: @example typedef void (*M_HOOKFN)(size_t sz, void *ptr); @end example @nondent in @file{stdlib.h}. > + Note that in some cases the parameters supplied to > + the ``callback'' function will be meaningless, in which case > + they will be zero or NULL as appropriate. In addition to function names, please also put any other symbols, such as ``NULL'' in @code{}. > + The callback function > + must NOT call any of malloc, free, or realloc. Please do not use caps for emphasis, as Texinfo has better means for doing that: either @emph{} (which typesets as italics) or @strong{} (which typesets as bold). > + For access to the internal storage of the malloc arena, see the > + _sysmalloc() call and the _sysinfo struct. Struct names, such as ``_sysinfo'', are also symbols, so please put them in @code{}. > ! This function allows diverting the output of the malldbg package > ! to any suitable text file. By default the package uses stderr. ``stderr'' is a symbol, so should be in @code{}. > ! The ohead value is not useful in the present > ! implementation. Please put ``ohead'' and other struct members in @code{}. Last but not least, thanks for working on this.