2004.03.31 15:54 "[Tiff] Questions about TIFF man pages", by Breda McColgan
Hello,
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?
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).
..."
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.
********************************************************************
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.
********************************************************************
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.
********************************************************************
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?
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?
********************************************************************
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?
********************************************************************
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
********************************************************************
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?
********************************************************************
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?
********************************************************************
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?
********************************************************************
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?
********************************************************************
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?
********************************************************************
Thank you :)
Breda.
cjpeg.1
djpeg.1
fax2ps.1
fax2tiff.1
gif2tiff.1
jpegtran.1
pal2rgb.1
ppm2tiff.1
ras2tiff.1
rdjpgcom.1
rgb2ycbcr.1
thumbnail.1
tiff2bw.1
tiff2ps.1
tiffcmp.1
tiffcp.1
tiffdither.1
tiffdump.1
tiffinfo.1
tiffmedian.1
tiffsplit.1
wrjpgcom.1
png.4
libpng.3
libjpeg.3
libpngpf.3
libtiff.3
TIFFReadDirectory.3tiff
TIFFReadEncodedStrip.3tiff
TIFFReadEncodedTile.3tiff
TIFFReadRawStrip.3tiff
TIFFReadRawTile.3tiff
TIFFReadRGBAImage.3tiff
TIFFReadRGBAStrip.3tiff
TIFFReadRGBATile.3tiff
TIFFReadScanline.3tiff
TIFFReadTile.3tiff
TIFFRGBAImage.3tiff
TIFFSetDirectory.3tiff
TIFFSetField.3tiff
TIFFsize.3tiff
TIFFstrip.3tiff
TIFFswab.3tiff
TIFFtile.3tiff
TIFFWarning.3tiff
TIFFWriteDirectory.3tiff
TIFFWriteEncodedStrip.3tiff
TIFFWriteEncodedTile.3tiff
TIFFWriteRawStrip.3tiff
TIFFWriteRawTile.3tiff
TIFFWriteScanline.3tiff
TIFFWriteTile.3tiff
TIFFbuffer.3tiff
TIFFClose.3tiff
TIFFcodec.3tiff
TIFFError.3tiff
TIFFFlush.3tiff
TIFFGetField.3tiff
TIFFmemory.3tiff
TIFFOpen.3tiff
TIFFPrintDirectory.3tiff
TIFFquery.3tiff
TIFFCheckTile.3tiff (shadow man page)
TIFFClientOpen.3tiff (shadow man page)
TIFFComputeStrip.3tiff (shadow man page)
TIFFComputeTile.3tiff (shadow man page)
TIFFCurrentDirectory.3tiff (shadow man page)
TIFFCurrentRow.3tiff (shadow man page)
TIFFCurrentStrip.3tiff (shadow man page)
TIFFCurrentTile.3tiff (shadow man page)
TIFFDefaultStripSize.3tiff (shadow man page)
TIFFDefaultTileSize.3tiff (shadow man page)
TIFFFdOpen.3tiff (shadow man page)
TIFFFileName.3tiff (shadow man page)
TIFFFileno.3tiff (shadow man page)
TIFFFindCODEC.3tiff (shadow man page)
TIFFFlushData.3tiff (shadow man page)
TIFFfree.3tiff (shadow man page)
TIFFGetMode.3tiff (shadow man page)
TIFFIsByteSwapped.3tiff (shadow man page)
TIFFIsMSB2LSB.3tiff (shadow man page)
TIFFIsTiled.3tiff (shadow man page)
TIFFIsUpSampled.3tiff (shadow man page)
TIFFLastDirectory.3tiff (shadow man page)
TIFFmalloc.3tiff (shadow man page)
TIFFmemcmp.3tiff (shadow man page)
TIFFmemcpy.3tiff (shadow man page)
TIFFmemset.3tiff (shadow man page)
TIFFNumberOfStrips.3tiff (shadow man page)
TIFFNumberOfTiles.3tiff (shadow man page)
TIFFRasterScanlineSize.3tiff (shadow man page)
TIFFReadBufferSetup.3tiff (shadow man page)
TIFFrealloc.3tiff (shadow man page)
TIFFRegisterCODEC.3tiff (shadow man page)
TIFFReverseBits.3tiff (shadow man page)
TIFFRGBAImageBegin.3tiff (shadow man page)
TIFFRGBAImageEnd.3tiff (shadow man page)
TIFFRGBAImageGet.3tiff (shadow man page)
TIFFRGBAImageOK.3tiff (shadow man page)
TIFFScanlineSize.3tiff (shadow man page)
TIFFSetErrorHandler.3tiff (shadow man page)
TIFFSetSubDirectory.3tiff (shadow man page)
TIFFSetWarningHandler.3tiff (shadow man page)
TIFFStripSize.3tiff (shadow man page)
TIFFSwabArrayOfLong.3tiff (shadow man page)
TIFFSwabArrayOfShort.3tiff (shadow man page)
TIFFSwabLong.3tiff (shadow man page)
TIFFSwabShort.3tiff (shadow man page)
TIFFTileRowSize.3tiff (shadow man page)
TIFFTileSize.3tiff (shadow man page)
TIFFUnRegisterCODEC.3tiff (shadow man page)
TIFFVGetField.3tiff (shadow man page)
TIFFVSetField.3tiff (shadow man page)
TIFFVStripSize.3tiff (shadow man page)
TIFFVTileSize.3tiff (shadow man page)
TIFFWriteBufferSetup.3tiff (shadow man page)