2004.03.31 15:54 "[Tiff] Questions about TIFF man pages", by Breda McColgan

2004.03.31 16:47 "Re: [Tiff] Questions about TIFF man pages", by Frank Warmerdam

I am a member of the Sun GNOME documentation team, and I am currently creating SGML versions of the TIFF man pages.

Can you please let me know whom I should credit as the original author(s) of these man pages?

Brenda,

To the best of my knowledge Sam Leffler is the primary author of the man pages, though of course a few came from other sources or were updated by others.

The libtiff.3 man page currently has the following text:

"
  Library Routines
     The following routines are part of the libtiff library.
     Consult specific reference pages for details on their opera-
     tion. The reference page names listed below are for systems
     where the full function names cannot be encoded in the file
     system. On most systems, the command man function-name will
     work.

     TIFFCheckTile
           Every x,y,z,sample is within image. See tile(3t).
..."

Strangely the wording is a bit different in the current libtiff.3t page that I see:

LIST OF ROUTINES
        The following routines are part of the library.  Consult specific  man-
        ual pages for details on their operation.  The manual page names listed
        below are for systems where the full function names can not be  encoded
        in  the  filesystem;  on  most systems doing ``man function-name'' will
        work.
        Name                   Appears on Page  Description
        TIFFCheckpointDirectory writedir.3t     writes the current state of the d irectory
        TIFFCheckTile          tile.3t          very x,y,z,sample is within image

I'm not sure if you are looking at old man pages or if your text is after "adjustment" to SGML format with some rewording.

This section raises several questions:

********************************************************************

1) I am not creating a "tile.3<x>" file. I am creating the following "tile"-related man pages:

- TIFFCheckTile.3tiff
- TIFFComputeTile.3tiff
- TIFFCurrentTile.3tiff
- TIFFDefaultTileSize.3tiff
- TIFFFileName.3tiff
- TIFFFileno.3tiff
- TIFFIsTiled.3tiff
- TIFFNumberOfTiles.3tiff
- TIFFReadEncodedTile.3tiff
- TIFFReadRawTile.3tiff
- TIFFReadRGBATile.3tiff
- TIFFReadTile.3tiff
- TIFFtile.3tiff
- TIFFTileRowSize.3tiff
- TIFFTileSize.3tiff
- TIFFVTileSize.3tiff
- TIFFWriteEncodedTile.3tiff
- TIFFWriteRawTile.3tiff
- TIFFWriteTile.3tiff

(a) Is the "tile.3<x>" file being created elsewhere for these "systems where the full function names cannot be encoded in the file system"?

(b) If the answer to (a) is yes, should I change the reference to "See tile(3tiff)" instead?

(c) If the answer to (a) is no, should I change the reference to "See

[one of the above tile-related man pages (probably TIFFtile)]" instead?

I've just used tile(3t) as an example. There are several other similar references, such as query(3t), open(3t), and so on.

I am not sure how the tile.3<x> file would get created on system that don't support the long names. I am not sure this is really a valid concern anymore. Keep in mind alot of this material is over 10 years old and there isn't much "project memory" on why things are the way they are.

(a) I don't know where or how tile.3t would get created.

(b/c) I would suggested referencing TIFFtile(3tiff) as that seems to be what is built and installed on modern systems.

********************************************************************

2) In some cases, the referenced file does not exist.

For example:

   "TIFFReadBufferSetup
    Specify i/o buffer for reading. See rdbuf(3t)."

There is no file TIFFrdbuf.3tiff. The TIFFReadBufferSetup.3tiff shadow file points to TIFFbuffer.3tiff.

There are several other references to non-existent files, such as readdir, rdestrip, and so on.

It would appear the longer names do not always have a direct relationship to the short names.

********************************************************************

3) In some cases, the reference points to an incorrect file.

For example:

   "TIFFSetWarningHandler
    Set warning handler function. See error(3t)."

This should point to the warning page (TIFFWarning.3tiff), not the error page (TIFFError.3tiff).

For example:

   "TIFFStripSize
    Return size of a strip. See size(3t)."

This should point to the strip page (TIFFstrip.3tiff), not the size page (TIFFsize.3tiff). Several other examples of this. Only TIFFScanlineSize and TIFFRasterScanlineSize should point to the size page.

Please file these as bug reports in the libtiff bugzilla and we will correct them.

********************************************************************

4) There are several references to items for which I have not created any man page (main or shadow):

- TIFFGetBitRevTable
- TIFFGetFieldDefaulted
- TIFFGetVersion
- TIFFVGetFieldDefaulted

a) In some cases, another man page refers to the item in the same way as to other items that do have shadow pages.

For example:

      "TIFFGetFieldDefaulted
           Return tag value in current directory. See getfield(3t)."

The TIFFGetField.3tiff man page has the following entry in the DESCRIPTION section:

       "TIFFGetFieldDefaulted and TIFFVGetFieldDefaulted are identi-
        cal  to TIFFGetField and TIFFVGetField, except that if a tag
        is not defined in the current directory and  has  a  default
        value, then the default value is returned."

There is a shadow page for TIFFVGetField, but not for TIFFGetFieldDefaulted and TIFFVGetFieldDefaulted.

Should I create a shadow page for each such reference?

I believe so yes, and of course file a bug so we can fix this upstream.

b) In other cases, there is no reference to the item except in the synopsis section of another man page.

For example:

        "TIFFGetBitRevTable
         Return bit reversal table. See swab(3t)."

The TIFFswab.3tiff man page has the following entry in the SYNOPSIS section:

       "const unsigned char* TIFFGetBitRevTable(int reversed);"

Should I create a shadow page for each such reference?

I suppose so. We are starting to get into functions that I don't think need to be widely used.

********************************************************************

5) The following man pages (some shadow, some main) are not listed in the quoted section of libtiff.3:

- TIFFbuffer.3tiff
- TIFFcodec.3tiff
- TIFFDefaultStripSize.3tiff
- TIFFDefaultTileSize.3tiff
- TIFFFindCODEC.3tiff
- TIFFfree.3tiff
- TIFFIsMSB2LSB.3tiff
- TIFFIsUpSampled.3tiff
- TIFFLastDirectory.3tiff
- TIFFmalloc.3tiff
- TIFFmemcmp.3tiff
- TIFFmemcpy.3tiff
- TIFFmemset.3tiff
- TIFFmemory.3tiff
- TIFFRasterScanlineSize.3tiff
- TIFFquery.3tiff
- TIFFReadRGBAStrip.3tiff
- TIFFReadRGBATile.3tiff
- TIFFrealloc.3tiff
- TIFFRegisterCODEC.3tiff
- TIFFRGBAImage.3tiff
- TIFFUnRegisterCODEC.3tiff
- TIFFsize.3tiff
- TIFFstrip.3tiff
- TIFFswab.3tiff
- TIFFtile.3tiff
- TIFFVStripSize.3tiff
- TIFFVTileSize.3tiff
- TIFFWriteBufferSetup.3tiff

Should I add a reference to these man pages to that section?

Yes, I suppose so and file a bug describing the issue.

********************************************************************

6. The following man pages referenced in the DESCRIPTION section of TIFFRGBAImage.3tiff, but are not referenced in the NAME section -- should they be referenced in the NAME section as shadow pages?

- TIFFRGBAImageOK
- TIFFRGBAImageBegin
- TIFFRGBAImageGet
- TIFFRGBAImageEnd

Yes, I imagine so, though I have never thought of those functions as being intended for public use.

********************************************************************

7. The TIFFRGBAImage.3tiff man page refers to TIFFReadRGBAImageOriented(3T) in the SEE ALSO section. I cannot find the TIFFReadRGBAImageOriented man page on the libtiff.org site -- should all references to this man page be removed? If not, can you please provide the text for the TIFFReadRGBAImageOriented man page? Should TIFFReadRGBAImageOriented be referenced in the NAME section of the TIFFRGBAImage.3tiff man page, as a shadow page?

There should presumably be a man page writte for it (or more likely it ought to be handled within the TIFFRGBAImage.3tiff with a shadow page). File a bug.

********************************************************************

8. TIFFVSetField is referenced in the DESCRIPTION section of TIFFSetField.3tiff, but is not referenced in the NAME section-- should TIFFVSetField be referenced in the NAME section as a shadow page?

I believe so.

********************************************************************

9. TIFFIsCODECConfigured is referenced in the DESCRIPTION section of TIFFcodec.3tiff, but is not referenced in the NAME section-- should TIFFIsCODECConfigured be referenced in the NAME section as a shadow page?

I believe so.

********************************************************************

10. The TIFFmemory.3tiff man page refers to several other shadow pages with a leading underscore -- is this correct, or should the leading underscore be removed? For example, which is correct: TIFFmalloc.3tiff or _TIFFmalloc.3tiff?

********************************************************************

The functions have underscores in front of them.

11. TIFFGetVersion is referenced in the DESCRIPTION section of TIFFquery.3tiff, but is not referenced in the NAME section-- should TIFFGetVersion be referenced in the NAME section as a shadow page?

********************************************************************

I believe so.

The man pages have only been half-heartedly updated for the last several years and, frankly, I have never really understand how shadow pages and so forth work well myself.

If you file bugs on the appropriate issues, Andrey should be able to clean things up in the next couple months.

Best regards,

---------------------------------------+--------------------------------------
I set the clouds in motion - turn up   | Frank Warmerdam, warmerdam@pobox.com
light and sound - activate the windows | http://pobox.com/~warmerdam
and watch the world go round - Rush    | Geospatial Programmer for Rent