[isabelle-dev] Consolidation of manual naming

[Makarius]

On Wed, 26 Mar 2014, Florian Haftmann wrote:

> since ancient times there is a glitch in the naming of manuals vs. their 
> originating sessions, e.g. isar-ref vs. IsarRef.
>
> Would it be worth an effort to consolidate this?  I regularly get 
> confused about that.

This is one of these recurrent (low priority) questions from distant past. 
Just a few days ago I was again thinking of it, but did not get the right 
idea where to move.

The short doc identifiers like "isar-ref" have a semi-formal status; they 
are relevant to "isabelle doc", the Isabelle/jEdit Documentation panel, 
and are published as global URLs (already for decades).  Changing that 
would cause a lot of confusion.


Session names cannot be changed either without violating increasingly 
important naming conventions: capitalized words usually separated by 
underscore.  Renaming IsarRef to Isar_Ref would make it look more modern, 
but still disagree with the document name "isar-ref".  (Note that a "-" 
within a session name is a legacy feature for many years alread.)

So what is actually the problem here?  The main practical situation where 
this connection of divergent names needs to be resolved is "isabelle 
build_doc".  That could be smarter, or actually somehow be automatic as 
part of the document viewer.  But we are talking about the Isabelle 
repository here, not a proper release.

I often just do "isabelle build_doc -a -j4" before viewing anything within 
the repository.


 	Makarius