Streamline .dtx files

[rchurchley]

This pull request makes mostly cosmetic changes to the new Documented LaTeX format files in an effort to make them a little easier to read. The highlights:

• a slightly different copyright notice which includes a link to the contributor list and removes LPPL-specific wording
• removes \CharacterTable, which checks against encoding problems that are now extremely rare
• removes the automatic changelog and index, which are not currently used
• rearranges package/driver code so LaTeX syntax highlighting is more informative

[matze]

Concerning the document format, I'd like to propose that we put the option documentation (i.e. what each option does) in a separate section rather than documenting them inline within the code. Are there any objections @rchurchley , @benjamin-weiss?

[rchurchley]

I was actually about to propose an overhaul of the options system using a key-value pair system and pgfopts. (I will create an issue for my proposal tomorrow and will be able to PR it sometime in the next couple days.)

Apart from that, I believe we are moving towards the following model of documentation:

• the portion of the manual that users actually care about is generated from mtheme.dtx. This will include things like descriptions of the package options.
• the portions of the manual describing the implementation is generated from beamerthemem.dtx and so on. The inline comments will be geared towards future contributors and explain the code and/or philosophy behind the implementation.

I think that means I agree with your proposal? :)

[matze]

I think that means I agree with your proposal? :)

Yes, indeed! By the way, I am looking forward to see the key-value option system.

[benjamin-weiss]

removes \CharacterTable, which checks against encoding problems that are now extremely rare

You kept the line % \CheckSum{0}. Is this line still necessary then?

I believe we are moving towards the following model of documentation: ...

Yes, what you describe was my intention when I created the .dtx files in the first place. So if nobody rejects this solution, I suppose we do it that way.

The changes you did look fine to me. Maybe when you or on it right now, you can also change the versioning system. The 3 digit system I introduced is probably way over the top. Speaking of the Package Version. As you probably have familiarized yourself with the .dtx system by now, do you have any idea why \date{\fileversion~from \filedate} isn't working?

[rchurchley]

You kept the line % \CheckSum{0}. Is this line still necessary then?

Checksumming is this crazy feature where we're supposed to manually keep track of the \CheckSum{n}, where n counts the \ characters in the package code. DocStrip puts up warnings if the checksum is off or if the checksum line is missing. Needless to say, I think the checksum feature is unnecessary, but the line \CheckSum{0} is necessary to turn it off.

The 3 digit system I introduced is probably way over the top.

I think semantic versioning is fine. Let's not worry about version numbers for a bit until development has stabilized and we can put a v1.0.0 tag on it. Afterwards, we increment the third digit for bug fixes, the second for feature adds, and the first digit whenever we break backwards compatibility (e.g. by removing package options).

Perhaps we should attach the semantic versioning to the bundle as a whole, however, and use date-versioning for the individual sub-packages.

As you probably have familiarized yourself with the .dtx system by now, do you have any idea why \date{\fileversion~from \filedate} isn't working?

We call \fileversion and \filedate in mtheme.dtx. But mtheme.dtx has a different format than the other .dtx files, is never compiled into a .sty file, and in particular does not contain the \ProvidesPackage line that would define \fileversion and \filedate. I've replaced that line with "v0.x.x" for now until we have a better solution.

[benjamin-weiss]

but the line \CheckSum{0} is necessary to turn it off.

Ok, now I get it.

I think semantic versioning is fine. Let's not worry about version numbers for a bit until development has stabilized and we can put a v1.0.0 tag on it. Afterwards, we increment the third digit for bug fixes, the second for feature adds, and the first digit whenever we break backwards compatibility (e.g. by removing package options).

If you explain it like that the semantic versioning does'n feel so much over the top anymore. So lets do it like that.

Perhaps we should attach the semantic versioning to the bundle as a whole, however, and use date-versioning for the individual sub-packages.

Is it even possible to use a pure date-versioning? As far as I understood \ProvidesPackage,

\ProvidesPackage{beamerthemem}
  [2015/06/12 A Modern Beamer Theme]

is interpreted as date=2015/06/12, version=A and description=Modern Beamer Theme.

We call \fileversion and\filedate in mtheme.dtx. But mtheme.dtx has a different format than the other .dtx files, is never compiled into a .sty file, and in particular does not contain the \ProvidesPackage line that would define \fileversion and \filedate.

That's why I tried to call \GetFileInfo on beamerthemem.dtx, yet still that doesn't work.

I've replaced that line with "v0.x.x" for now until we have a better solution.

All right, for now that's fine.

[rchurchley]

That's why I tried to call \GetFileInfo on beamerthemem.dtx, yet still that doesn't work.

In that case, it must be because mtheme.dtx doesn't call \usepackage{beamerthemem}. I believe \GetFileInfo requires the package to be loaded in order to get the file version and date.

Is it even possible to use a pure date-versioning?

I was mistaken --- \GetFileInfo does work the way you describe. I suppose we will figure out the versioning when we reach 1.0.0.

[benjamin-weiss]

Alright lets save this problem for a later time. It really doesn't matter that much until we release on CTAN. I will open a separate issue to help us remember the problem. @matze So I think we can merge this now.