Comments interspersed. Let me say right away that, as far as this goes,
it all seems sensible. But, as I'll say below, it doesn't address what
has always been the most serious problem.
On 03/25/2016 02:34 AM, Scott Kostyshak wrote:
> 3. The LaTeX class file associated with the layout have been updated.
>
> (3) is the most complicated case and the rest of this discussion is focused
> on it. We can break down (3) further:
>
> 3a. The updated class or style files are named differently.
>
> See e.g. #10027. aastex.cls is now aastex6.cls. In this case, we should add a
> note to the template using this layout stating that the template is for an
> obsoleted version of aastex which is no longer bundled with the newest TeX
> distributions (e.g. TeX Live and MikTeX). State in the note explicitly that
> the user should not use the old template for new documents where the
> intention is to submit to a journal that uses the updated LaTeX class. That
> note should be added to our template in both master and branch, and should be
> added even if we do not have a layout or template for the newer version of
> the LaTeX class.
>
> We should ideally create a new layout corresponding to the new cls file, and
> a new template corresponding to the new layout. This layout and template can
> go into master and should be posted on the wiki so that users on branch can
> immediately have access to it. The files should not be put into branch (more
> on this below).
>
> In master, since we will have multiple layouts, we should move the common
> parts of the old and new layout files into a .inc file that is included in
> both layout files.
>
> In the example (#10027), the new layout name would be aastex6.layout and the
> new template name would be aastex6.lyx. If we do not immediately create a
> layout and template for the updated class file, we should create a feature
> request that states the situation and links to the changelog of the updated
> LaTeX class, if it is available so that it is clear what must be done.
>
> LyX configure shall check for both class files (e.g. aastex.cls and
> aastex6.cls). Then, the usual warnings for missing class files and missing
> styles will guide the user in the transition, so that no file format change
> is required.
>
> Once we have a new template, the old template (but not layout file) should be
> removed in master, but not in branch. The new layout and template should be
> added to master and not to branch. We should change the branch template,
> which is for the old version and which has an "obsoleted note" (as detailed
> above), to mention explicitly that a new template and layout file are
> available on the Wiki page (and give a direct link to the wiki page). We
> already have instructions on how to add a new layout [2]. I cannot think of
> how to make them more user-friendly.
>
> It is tempting to say that we should just add the new template and new layout
> to branch. Indeed, since the class file has a different name (recall that we
> are still in the case where the new class file is called aastex6.cls and the
> old class file is called aastex.cls), this would be straightforward. However,
> in my opinion this would cause more confusion for users than it would help.
> If two users are working together and one uses e.g. LyX 2.2.2 and the other
> uses LyX 2.2.3, if we add a layout to 2.2.3 and the user of 2.2.3 creates a
> document based on it and sends that document to the user on 2.2.2, the user
> on 2.2.2 will not be able to open the document without installing the new
> layout from the wiki. I think it would create less confusion for users if we
> just require both the user of 2.2.2 and 2.2.3 to download and install the new
> layout from the wiki. This relates to our goal that there should be as few
> changes as possible between minor versions, except for bug fixes.
I don't myself see why we shouldn't add the new layout file, which is
this case is completely new, to branch. No conflict can arise in this
case, other than that one user has the layout file and the other
doesn't. Sure, both users could download it, but it would be easier for
one of them to download it. And if one of them has downloaded it and the
other hasn't, then one of them has it and the other doesn't, and it's
not very different from what happens if we included it in the distro.
Note also that putting it in the distro advertises the existence of the
new layout.
> 3b. The .cls file has been updated but uses the same name.
>
> 3bi. Only new styles have been added.
> - Regarding branch, this is covered in the section of Development.lyx that
> is currently "2.6 Backporting new styles to the stable version"
> - Regarding master, we can just update the layout directly without any of
> the renaming of files that was necessary in (3a).
Let me just say thanks again to Georg for sorting this out.
> 3bii. It is not just that new styles have been added.
>
> Suppose that there is a class file with the same name and with two
> incompatible versions, say foo.cls v1 and foo.cls v2. Suppose that LyX
> supported v1 with a layout called foo.layout. In master we should add support
> for v2, calling it foo.layout but still support the old one by copying the
> old foo.layout file to foo1.layout. The file templates/foo.lyx in master
> should be updated to use the new layout (foo.layout).
>
> lyx2lyx can convert old files (made for v1) to use foo1.layout with the new
> LyX version. This way, no other change to the document is required and users
> with the old class file can still compile old documents. Another advantage is
> that only minimal lyx2lyx code is required (so there is a small chance of
> introducing bugs). Note that our export to older LyX versions should also
> change the layout back: foo.layout in 2.1.x is equivalent to foo1.layout in
> 2.2.x.
>
> Similar to the case of (3a), we can have a .inc file that contains the shared
> code between foo.layout and foo1.layout.
>
> [It is not clear how long we should keep old layouts around and where we
> should put the old layouts. Previous discussions have mentioned a "layout
> attic". We should consider solutions that would not clutter the already messy
> layout selection. Perhaps a checkbox that is unchecked by default that says
> "show deprecated layouts" ?]
>
> A user can convert old documents to v2 manually by changing Document >
> Settings > Document class from foo1 to foo. This will trigger some
> "obsoletedby" layout replacements and may still require manual adaptation.
This all seems reasonable to me. But it leaves open the most contentious
issue: What to do about this in stable? Uwe's concern is always that, if
we don't do anything, then it's impossible to use LyX to produce papers
you can submit to journals that require the new class file. Unless, of
course, you write your own layout file. That does not seem like a good
situation. This sort of thing could happen two days after 2.2.0 is
released. The problem on the other side is that simply updating the
layout file breaks the files of people (or journals) that are still
using the old version.
I see a number of options.
(1) Just post a new layout file on the wiki and people can get it from
there. That's not an unreasonable solution, though I'm not sure people
know about the wiki so much. Then again, what is likely to happen is
that people start getting LaTeX errors with an updated version of the
class file, and then hopefully they ask on the list.
So this isn't terrible, but I think we can do better.
(2) Handle this in stable inversely to how we handle it in master.
Introduce a new layout file, foo-v42.layout, or whatever. Perhaps we
could then introduce some machinery that will tell users of the old
layout file about the new one (once, maybe). We could then use lyx2lyx
to convert files that use foo-v42.layout in stable to files that use
foo.layout in master. Backporting can then go the other way.
This seems to me fairly reasonable, but on thinking about this more I
think we can do better and also do it more simply.
(3) All the changes needed to go from the old version of the layout file
to the new one could surely be encapsulated in a module, say,
foo-v42.module. You can use the new class then just by using the new
module. New layouts can of course be introduced that way. Old layouts
that don't work at all anymore could be removed via NoStyle, could be
ObsoltedBy, or could be highlighted in red or something, and we could
define some null operation that would at least allow the document to
compile, e.g.: \newcommand\badcmd[2]{}. Here again, we might have some
machinery that would tell the user about the new module (once). The same
lyx2lyx code that changes foo.layout in stable to foo-v42.layout (or
whatever) in master can remove the dependence on the module. We don't
need that in master.
Now MAYBE there's some way of doing this same sort of thing using the
ForceLocal idea (see Development.lyx, 2.6). I don't immediately see how
to do that, and it would be a format change anyway so is too late for
2.2. Still, if we could figure that out, it might give us a general
solution to what has been a long-standing problem.
But it seems to me that a better long-term solution would be:
> ***1 class version detection
> https://www.mail-archive.com/lyx-devel@lists.lyx.org/msg192467.html
>
> However, what we really need is version detection for the configuration,
> so that the user can be warned if the required class file has the wrong
> version. (If the class file keeps the name over the version change, only one
> of the two layout files generates compilable documents.)
>
> This point was also made here:
> http://permalink.gmane.org/gmane.editors.lyx.devel/143798
>
> Long-term, as I said, we should make layouts version-aware somehow, at
> least in so far as we try to detect version during configuration and enable
> or disable layouts depending upon which versions we detect. I can even
> imagine putting conditional code into layouts themselves.
That handles all the problems here, and I propose to make implementing
this my first job for 2.3. So I think we need a short-term solution for
2.2, and my own preference, I think, is for (3). It is extremely clean
and simple.
> If a developer cares enough it would even be possible to put some
> intelligence into lyx2lyx: Search through the document for the problematic
> styles, and only convert the document class to the one for acmsiggraph.cls
> version 0.80 if one of them is found.
This might be reasonable on a case by case basis, but it seems fragile.
> ***3 Download layouts from our wiki online
> http://permalink.gmane.org/gmane.editors.lyx.devel/143744
>
> New layouts would not require a file format change, if there was an
> official layout repository on lyx.org, and LyX would be able to download a
> missing layout automatically. Then new layouts could be shipped in stable
> releases and at the same time made available online, so that an older stable
> version would simply download the missing layout file. For people without
> internet connection a proper error message giving hints for manual
> installation would be issued. Of course this procedure could only be
> introduced in 2.1 or later, since current 2.0.x has no download capability.
> Some thoughts on security should be spent as well, i.e. it should be possible
> to disable this feature.
Whatever the virtues of this idea, it doesn't help that much with the
problems we're discussing. We can't just ship new versions of layouts
with new stable releases if those are going to break the documents of
people still using older versions of the class file.
Richard
