AWARE SYSTEMS
TIFF and LibTiff Mail List Archive

Thread

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
2004.03.31 17:32 "Re: [Tiff] Questions about TIFF man pages", by Breda McColgan
2004.04.14 10:40 "[Tiff] More man pages added to gnome-docu/gdp/contrib/manpages", by Breda McColgan
2004.04.14 11:07 "Re: [Tiff] More man pages added to gnome-docu/gdp/contrib/manpages", by Andrey Kiselev
2004.04.14 11:35 "Re: [Tiff] More man pages added to gnome-docu/gdp/contrib/manpages", by Breda McColgan
2004.04.14 12:30 "Re: [Tiff] More man pages added to gnome-docu/gdp/contrib/manpages", by Andrey Kiselev
2004.04.14 12:52 "Re: [Tiff] More man pages added to gnome-docu/gdp/contrib/manpages", by Breda McColgan
2004.04.14 13:04 "Re: [Tiff] More man pages added to gnome-docu/gdp/contrib/manpages", by Andrey Kiselev

2004.03.31 17:32 "Re: [Tiff] Questions about TIFF man pages", by Breda McColgan

Hi Frank,

many thanks for your prompt and helpful reply :)

See my comments embedded below.

Regards,
Breda.

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.

Unless I hear otherwise, I'll credit Sam Leffler in all 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).
..."

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.

My apologies. I should have clarified that I had indeed reworded and reformatted the text. There is a known problem with tables in man pages, so I did this to move the text from a table into a variable list.

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.

Will do.

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

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.

Again, I'll replace with references to known 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.

Will do.

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

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.

Will do.

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.

Ok, thanks.

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

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.

Will do.

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

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.

Ok, thanks.

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

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.

Will do.

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

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.

Ok, thanks.

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

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.

Ok, thanks.

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

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.

Ok, thanks.

 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.

Ok, thanks.

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.

I need to issue a first draft of these man pages by next week. I'll log the bugs as soon as possible after that.

I'll also put the final draft of the SGML man pages into GNOME CVS, and let you know the location.

You are of course very welcome to use those updated man pages.

Thanks again!