packages and TeXLive revisions

[Brook Milligan]

I notice that a number of (but I don't believe all of) the TeXLive packages, i.e., those in print/tex-* indicate a TeXLive revision either as a comment in the Makefile or as an defined Makefile variable. I have some new packages that I wish to commit, but I am not sure what to make of the revision information. In general, I don't seem to have any such information for these packages, so I am wondering where this comes from, what it means, and if I am missing something as I prepare these packages.

Thanks for your help.

Cheers,
Brook

[Thomas Klausner]

Post by Brook Milligan
I notice that a number of (but I don't believe all of) the TeXLive packages, i.e., those in print/tex-* indicate a TeXLive revision either as a comment in the Makefile or as an defined Makefile variable. I have some new packages that I wish to commit, but I am not sure what to make of the revision information. In general, I don't seem to have any such information for these packages, so I am wondering where this comes from, what it means, and if I am missing something as I prepare these packages.

TeXLive packages usually contain files describing their content. For
example (picked at random), tex-pst-geo contains a file
tlpkg/tlpobj/pst-geo.tlpobj that starts with:

name pst-geo
category Package
revision 17751
shortdesc Geographical Projections
relocated 1
longdesc pst-geo is a set of PSTricks related packages for various
...


The 'revision' field here contains the revision you're looking for.

Some packages do not contain such a file. I'm not sure how to find the
revision out for those.
Thomas

[Brook Milligan]

Thomas,

Thanks.

Post by Thomas Klausner

Post by Brook Milligan
I notice that a number of (but I don't believe all of) the TeXLive packages, i.e., those in print/tex-* indicate a TeXLive revision either as a comment in the Makefile or as an defined Makefile variable. I have some new packages that I wish to commit, but I am not sure what to make of the revision information. In general, I don't seem to have any such information for these packages, so I am wondering where this comes from, what it means, and if I am missing something as I prepare these packages.

TeXLive packages usually contain files describing their content. For
example (picked at random), tex-pst-geo contains a file
name pst-geo
category Package
revision 17751
shortdesc Geographical Projections
relocated 1
longdesc pst-geo is a set of PSTricks related packages for various
...
The 'revision' field here contains the revision you're looking for.

So should that be a comment in the Makefile or an actual defined make variable? I have seen both. (I have also seen packages with neither.) Is this documented anywhere?

Cheers,
Brook

[Thomas Klausner]

Post by Brook Milligan
So should that be a comment in the Makefile or an actual defined make variable? I have seen both. (I have also seen packages with neither.) Is this documented anywhere?

I think it's commonly used to keep the distfiles separate, since they
are unversioned; so usually DIST_SUBDIR is set using the revision. A
few packages have separate version numbers, so that can be used for
the DIST_SUBDIR as well. I think revision is just the fallback if such
a version number does not exist.

So define if you need it for DIST_SUBDIR, make it a comment if not.

I think much of the TeXLive handling in pkgsrc is not described,
sadly. I'm also just guessing from looking at some of the packages and
updating some.
Thomas

[Brook Milligan]

Post by Thomas Klausner

Post by Brook Milligan
So should that be a comment in the Makefile or an actual defined make variable? I have seen both. (I have also seen packages with neither.) Is this documented anywhere?

I think it's commonly used to keep the distfiles separate, since they
are unversioned; so usually DIST_SUBDIR is set using the revision. A
few packages have separate version numbers, so that can be used for
the DIST_SUBDIR as well. I think revision is just the fallback if such
a version number does not exist.
So define if you need it for DIST_SUBDIR, make it a comment if not.

So I believe this is the basic idea of what happens based upon the contents of print/texlive/package.mk:

- If TEXLIVE_REV is not defined, the DIST_SUBDIR is ${PKGNAME_NOREV}, i.e., basically the normal package name.
- If TEXLIVE_REV is defined, the DIST_SUBDIR is ${PKGBASE} without any -doc suffix plus TEXLIVE_REV.

I think this means the following:

- If the package has a proper version, include that in the definition of PKGNAME and do not define TEXLIVE_REV (use a comment instead).
- If the package has no version, do not include any version in PKGNAME and define TEXLIVE_REV from the tlpkg/tlpobj/*.tlpobj file.
- There is no need to make any reference to DIST_SUBDIR as it will be set automatically.

Perhaps that just repeats what you said, but I wanted to be more explicit for future reference. Does this sound about right?

Cheers,
Brook

[Thomas Klausner]

Post by Brook Milligan
- If TEXLIVE_REV is not defined, the DIST_SUBDIR is ${PKGNAME_NOREV}, i.e., basically the normal package name.
- If TEXLIVE_REV is defined, the DIST_SUBDIR is ${PKGBASE} without any -doc suffix plus TEXLIVE_REV.
- If the package has a proper version, include that in the definition of PKGNAME and do not define TEXLIVE_REV (use a comment instead).
- If the package has no version, do not include any version in PKGNAME and define TEXLIVE_REV from the tlpkg/tlpobj/*.tlpobj file.
- There is no need to make any reference to DIST_SUBDIR as it will be set automatically.
Perhaps that just repeats what you said, but I wanted to be more explicit for future reference. Does this sound about right?

That sounds about right. If you can find a good section in the pkgsrc
guide, can you please add it there?

Thanks,
Thomas

[Leonardo Taccari]

Hello Brook and Thomas,

Post by Thomas Klausner

Post by Brook Milligan
- If TEXLIVE_REV is not defined, the DIST_SUBDIR is ${PKGNAME_NOREV}, i.e., basically the normal package name.
- If TEXLIVE_REV is defined, the DIST_SUBDIR is ${PKGBASE} without any -doc suffix plus TEXLIVE_REV.
- If the package has a proper version, include that in the definition of PKGNAME and do not define TEXLIVE_REV (use a comment instead).
- If the package has no version, do not include any version in PKGNAME and define TEXLIVE_REV from the tlpkg/tlpobj/*.tlpobj file.
- There is no need to make any reference to DIST_SUBDIR as it will be set automatically.
Perhaps that just repeats what you said, but I wanted to be more explicit for future reference. Does this sound about right?

That sounds about right. If you can find a good section in the pkgsrc
guide, can you please add it there?

What do you think about the following (attached) diff
for print/texlive/package.mk? (something stolen from PR 49070 and big
inspiration from this mail too)


Ciao,
L.

[Brook Milligan]

Post by Leonardo Taccari
What do you think about the following (attached) diff
for print/texlive/package.mk? (something stolen from PR 49070 and big
inspiration from this mail too)

Nice job. However, since sending my earlier email I noticed that common practice may be a bit mixed and it would be good to codify (as you have started to do) exactly what we want going forward. I was going to review that common practice a bit more systematically and report back, but haven't quite had the chance yet. Would you mind waiting to commit this until I have a chance to do that and we can be better sure that it describes exactly what we want. Then perhaps we can add your (or a modified) patch and one to the guide as well.

Cheers,
Brook

[Brook Milligan]

Once again, thanks for writing the new documentation. Here is the outcome of my analysis of the TeX Live packages. In case anyone cares, I have attached the Makefile and the default target's output that underlies part of this analysis. Below is a summary of the numeric results, some observations, consequences/questions, and suggestions for improving the documentation. For my own benefit, I would appreciate responses to the questions and any comments about the rest. If you wish to make use of the suggested documentation, please do.

Overall summary of packages (see Makefile for how the numbers were generated):

Number Description Criterion
617 TeX packages print/tex-* directories
603 TeX Live packages include texlive/package.mk
14 other TeX packages print/tex-* without texlive/package.mk
518 TeX Live packages with rev. TEXLIVE_REV defined
85 TeX Live packages without rev. TEXLIVE_REV not defined (all could be defined)
30 explicit DIST_SUBDIR TeX Live packages with DIST_SUBDIR defined (none are needed)

Observations:
- All TeX Live packages seem to have revision information in
tlpkg/tlpobj/*tlpobj (only checked ones lacking TEXLIVE_REV assuming
others got the information from there in the first place)

- All TeX Live packages either have a version (part of CRAN submission
form) or could (e.g., YYYYMMDD-based)

- relevant texlive/package.mk fragment
.if empty(TEXLIVE_REV)
DIST_SUBDIR?= ${PKGNAME_NOREV}
.else
DIST_SUBDIR?= ${PKGBASE:S/-doc$//}-${TEXLIVE_REV}
.endif

Consequences/questions:
- All TeX Live packages could define ${TEXLIVE_REV}
+ None need a comment mentioning "TeX Live Revision"

- All TeX Live packages could have DIST_SUBDIR defined consistently by
the second branch in package.mk
+ None need an explicit DIST_SUBDIR
+ First branch in package.mk is probably useful to catch mistakes,
but why ${PKGNAME_NOREV} instead of ${PKGBASE:S/-doc//}? If the
latter is ok, why not replace the entire conditional with the
following:

DIST_SUBDIR?= ${PKGBASE:S/-doc$//}${TEXLIVE_REV:D-${TEXLIVE_REV}}

+ Why not emit a warning of some kind if DIST_SUBDIR is defined?

- Some examples of oddities in existing packages:

+ tex-a4wide/Makefile:PKGNAME= tex-${DISTNAME}-2010 # why not YYYYMMDD?
+ tex-amscls/Makefile:PKGNAME= tex-${DISTNAME}-2010.20248 # why mix of date/revision?

- What are the consequences of switching to a consistent DIST_SUBDIR
definition based entirely on TEXLIVE_REV?

Suggestions for modifying the documentation patch:

Note to package developers:

* When creating/updating a TeX package, please set TEXLIVE_USE_CTAN
either in mk.conf or in the environment. This will enable proper
updating of the distinfo via the "makesum" target. Additionally,
be sure to define TEXLIVE_REV (see below) and include the file
"../../print/texlive/package.mk" in the package Makefile. Note
also that some TeX Live packages have versions (e.g., date-based)
containing hyphens (-); the hyphens should be removed in the
package Makefile.

TEXLIVE_REV
A string used to define DIST_SUBDIR that is useful to
differentiate among distfiles because ${DISTNAME} will generally
not include a revision number. The value of TEXLIVE_REV should be
taken from the "revision" line present for each package in
${WRKSRC}/tlpkg/tlpobj/${DISTNAME}.tlpobj.

I hope this is helpful. Thanks for any input you can offer.

Cheers,
Brook

[Brook Milligan]

Once again, thanks for writing the new documentation. Here is the outcome of my analysis of the TeX Live packages. In case anyone cares, I have attached the Makefile and the default target's output that underlies part of this analysis. Below is a summary of the numeric results, some observations, consequences/questions, and suggestions for improving the documentation. For my own benefit, I would appreciate responses to the questions and any comments about the rest. If you wish to make use of the suggested documentation, please do.

Overall summary of packages (see Makefile for how the numbers were generated):

Number Description Criterion
617 TeX packages print/tex-* directories
603 TeX Live packages include texlive/package.mk
14 other TeX packages print/tex-* without texlive/package.mk
518 TeX Live packages with rev. TEXLIVE_REV defined
85 TeX Live packages without rev. TEXLIVE_REV not defined (all could be defined)
30 explicit DIST_SUBDIR TeX Live packages with DIST_SUBDIR defined (none are needed)

Observations:
- All TeX Live packages seem to have revision information in
tlpkg/tlpobj/*tlpobj (only checked ones lacking TEXLIVE_REV assuming
others got the information from there in the first place)

- All TeX Live packages either have a version (part of CRAN submission
form) or could (e.g., YYYYMMDD-based)

- relevant texlive/package.mk fragment
.if empty(TEXLIVE_REV)
DIST_SUBDIR?= ${PKGNAME_NOREV}
.else
DIST_SUBDIR?= ${PKGBASE:S/-doc$//}-${TEXLIVE_REV}
.endif

Consequences/questions:
- All TeX Live packages could define ${TEXLIVE_REV}
+ None need a comment mentioning "TeX Live Revision"

- All TeX Live packages could have DIST_SUBDIR defined consistently by
the second branch in package.mk
+ None need an explicit DIST_SUBDIR
+ First branch in package.mk is probably useful to catch mistakes,
but why ${PKGNAME_NOREV} instead of ${PKGBASE:S/-doc//}? If the
latter is ok, why not replace the entire conditional with the
following:

DIST_SUBDIR?= ${PKGBASE:S/-doc$//}${TEXLIVE_REV:D-${TEXLIVE_REV}}

+ Why not emit a warning of some kind if DIST_SUBDIR is defined?

- Some examples of oddities in existing packages:

+ tex-a4wide/Makefile:PKGNAME= tex-${DISTNAME}-2010 # why not YYYYMMDD?
+ tex-amscls/Makefile:PKGNAME= tex-${DISTNAME}-2010.20248 # why mix of date/revision?

- What are the consequences of switching to a consistent DIST_SUBDIR
definition based entirely on TEXLIVE_REV?

Suggestions for modifying the documentation patch:

Note to package developers:

* When creating/updating a TeX package, please set TEXLIVE_USE_CTAN
either in mk.conf or in the environment. This will enable proper
updating of the distinfo via the "makesum" target. Additionally,
be sure to define TEXLIVE_REV (see below) and include the file
"../../print/texlive/package.mk" in the package Makefile. Note
also that some TeX Live packages have versions (e.g., date-based)
containing hyphens (-); the hyphens should be removed in the
package Makefile.

TEXLIVE_REV
A string used to define DIST_SUBDIR that is useful to
differentiate among distfiles because ${DISTNAME} will generally
not include a revision number. The value of TEXLIVE_REV should be
taken from the "revision" line present for each package in
${WRKSRC}/tlpkg/tlpobj/${DISTNAME}.tlpobj.

I hope this is helpful. Thanks for any input you can offer.

Cheers,
Brook