Plan for XML documentation

[timj]

Starlink has a few documents that were written in XML rather than LaTeX. These documents use a completely different build system and rely on components that are no longer supported (e.g. Jade). Currently they are not installed and not included in the updates to the build system when fixing #4.

5 has some comments from @nxg and @MalcolmCurrie concerning the XML documentation.

The documents have some useful information so the issue is what we do with them? One option is to indicate that the documents are frozen and generate PDF versions that are installed without attempting to do an automated build. This would seem to be the pragmatic solution. Certainly less work than attempting to rejig the build using modern tools.

[timj]

@nxg has built the PDFs (I think he did HTML as well) so we could now disable the attempt to build from SGML and simply copy the files during install.

[nxg]

Building these isn't hugely hard (see the notes at the very bottom of $TOP/README), but it's probably not really worth the effort to automate that. I think we can say that the (SG|X)ML build system is now officially dead.

So yes, @timj, the PDFs I sent to you should now (in a spirit of very proper pragmatism) just be checked in.

Sic transit my 1999-2000; c'est la vie académique. Drink up.

[grahambell]

Might another option to be to convert them to the new LaTeX system? I think I found an original .tex file for one of them once in the repository history. I could have a go at converting the other two.

[timj]

I was wondering if that might not be the easiest solution in the longer term. We are talking about SC/13 (theory cookbook), SSN/78 (Starlink build system), SUN/248 (building Starlink software), SSN/71 (dvibitmap) and SSN/70 (sgmlkit). Although the last one would be a tad ironic to convert given that it's the sgmlkit application.

One could make the case that all five of these documents are not required any more. The two build documents could be moved to docs/obsolete with the PDFs added. We can move sgmlkit to applications/obsolete and put the PDF in there. dvibitmap would then not be used even in theory and could be removed from thirdparty with the document moved into docs/obsolete along with the PDF so that we don't lose it.

That really only leaves the theory and modeling cookbook as the one which could usefully be migrated to latex (even though I imagine a lot of the content is now outdated).

[nxg]

If SSN/78 and SUN/248 are converted to star2html, then the entire sgmlkit becomes obsolete, and can indeed be moved to obsolete. If so, then I agree that SSN/70 and SSN/71 should go there, too (though it would indeed be good to preserve the PDF).

Slightly less of SC/13 is fully obsolete, than you might think. Section 2 (programming and floating point topics) is high-level enough that it hasn't changed much in the last decade, and I think it's a decent piece of work – I was quite proud of that; Section 5 (LaTeX) would need minimal updating, for much the same reason, but much of this information can be found elsewhere. Section 3 is probably old, Section 4 is certainly old, and Section 6 is so short as to be discardable without anyone noticing.

All that said, I don't think it would be vitally necessary to convert SC/13, but feel free to disagree!

[MalcolmCurrie]

Hurrah for the official end of (SG|X)ML Starlink documents. We've known for years, but the hear it from the horse's mouth is both jaw-dropping and reassuring.

An obsolete SSN/78 highlights that we don't have a document that describes the current build system. Substantial chunks of SSN/78 surely still apply. Don't we still need an updated SUN/248? "Building Starlink software" is surely still a relevant topic.

There are quite a few documents which have not been maintained and in general they're only updated when there is demand.

[grahambell]

I converted SC/13 as discussed above in commit 4c6f99b26a6bdf66c4dd8071cdbe6e2710a8d043.

[sfgraves]

SSN/78 has been converted to latex in commit a382d8608eab9466

Graham suggested earlier today that anything still current in SUN/248 should be noted in the README file (which has effectively replaced it, and already has much of the relevant information). After that, SUN/248 could be obsoleted.

[sfgraves]

Having taken a quick look at SUN/248, I think all of the information in it can be classed as either included or superseded by information in the README. I'm going to move this to obsolete. Any references to SUN/248 in the existing code should be updated to point readers towards the README. (If anyone thinks I missed anything useful, please add it to the README file.)

[timj]

And after that you can move applications/sgmlkit to obsolete as well and disable dvi2bitmap.

[sfgraves]

This was done in commits 8ebeefbd3f76882e (sgmlkit) and 1f57baba024047b95580cd (dvi2bitmap)

[timj]

I think this means the issue is closed. Thanks.