Want to take part in these discussions? Sign in if you have an account, or apply for one below
Vanilla 1.1.10 is a product of Lussumo. More Information: Documentation, Community Support.
Have just begun taking a look at the source code of instiki. A propos of the recent discussion here, it would in fact be trivial to change the numbering to sequential rather than per environment: there is no coding at all really, it is just done by css!
We discussed whether to have an option to set the numbering to be sequential or per environment. Now is the time for a decision on this:
a) should we have the option?
b) how do you wish to implement it (i.e. where should it appear on a page, etc)?
c) what should be the default?
d) should we alter existing pages?
It is also trivial to add further environments, so if anybody would like some tweaks on that front, let me know. I would like to add ’Notation’ and ’Terminology’.
Interesting, thanks! Would this be an option set by the reader or by the author of a page? On the one hand it affects readers more directly, so it would be nice if I could read a page the way I want and Todd could read it the way he wants. But on the other hand, having it set by readers would mean that different readers would see different numbers assigned to the same theorem, which might be problematic if trying to refer to a particular theorem somewhere other than on the same nLab page, where \ref isn’t an option.
I think adding “Notation” would be a great idea. But how does “Terminology” differ from “Definition”?
If it’s up to the reader and he/she could toggle back and forth, then I don’t see any problem at all. If ever I want to refer Mike to an environment, I’m happy to use sequential numbering.
I’d like to think about it some more, but I might even be willing to cede the argument to Mike or whoever else prefers sequential numbering – provided that I get to keep my own web the way I want. (But I don’t know whether that’s possible.) Of course it goes without saying that more people should be in on the decision.
By the way, for sequential numbering, if or where it is implemented, it would be good to have
5) Theorem
instead of
Theorem 5 .
And while you are at it: would it be easy to make automatic numberings of sections and subsections? (1 then 1.1 and 1.2, then 2 etc.)
If so, would it be possible to combine this and have the second definition sitting in section 1.1 be labeled
1.1 - 2) Definition
?
I very much agree with Urs’s “instead of”, and that would certainly bring me closer to being fine with sequential numbering.
I actually don’t agree with that. When you refer to a theorem, do you say “See 5) theorem”? Normally we say “See theorem 5”, so it seems to me the definition of “Theorem 5” should agree with what we are referring to.
Books with sequential numbering don’t say “by theorem xyz”, they say “by 1.3 2)”.
Yes they do. I just pulled three at random off my shelf to check.
The more I think about it, the more I think the choice should lie with the author, if we want the nLab to be at all citeable. Referring each other to theorems informally is one thing, but if someone writing a paper wants to cite a theorem on the nLab, they should be able to give it an unambiguous number (once they specify the page version, of course), and they shouldn’t be expected to realize that the numbers assigned depend on an option set by the reader.
Here’s a thought for an easy way to implement that. We’ve already noticed that the system doesn’t care what you actually label the proclamation (e.g. a num_note can be labeled “Notation” or “Theorem” or “Definition” or whatever you like). The only reasons to have different environments num_theorem, num_defn, etc. are (1) if you want them to use separate counters, or (2) because you want them to look different, e.g. theorems are in italics but definitions are not. So we could keep the existing environments, numbered with separate counters, and add (say) two more num_itproc and num_rmproc that use the same counter and where the first is italic and the second not; then someone who wants to get sequential numbering can just use the latter two for all of their proclamations, but all existing pages will stay the same unless someone decides to port them.
I’m with Mike on this one, I would keep things the same as in Latex. I myself always reference things as: Theorem 1.3.2. But again, if there is a desire, I can add an option to do things differently.
Automatic numbering by subsection as you suggest should be no problem, Urs.
Good question regarding whether the reader or author should be able to choose the rendering. If the reader, one would want to store the preference in the cache, I guess. As pointed out, it could lead to a bit of ambiguity when referencing, though, if the reader can choose. I plan to add referencing across pages in the nLab itself, so that would not be a problem, but it might be an issue for people on other sites who just mention a particular thing. I am not sure either way yet as to which I prefer.
Regarding ’Terminology’, I often use this for minor things, like ’an n-simplex of a simplicial set’, reserving ’Definition’ for a more substantial notion. But I’m not fanatical about having it.
It should not be a big task, Todd, to have personal webs have different configurations than the main nLab. I imagine that they are different instances of instiki, so one could just add a command line option to tweak things or not when deploying instiki.
I’m pretty sure that the personal webs are all just “webs” in the same running instance of instiki.
On a different note, I’m toying with the idea of starting afresh, as I mentioned in the other thread. The nLab is quite large, and Ruby on Rails (which instiki is written in) is known for not scaling that well, which might contribute to the nLab’s sometimes poor performance. But this is pure speculation on my part.
But Ruby on Rails is not a language I’m very familiar with, so I might be able to get up a reasonable working replacement in just as quick a time as it takes me to find my way around instiki’s source code. I love Haskell and other functional programming languages, but I would probably use Scala or just plain Java, as I use Java in my day to day work. In particular, something in Haskell would be more experimental performance wise, whereas Scala and Java are widely used for web applications. Rather to my surprise, coming from a functional programming background, I actually have come to appreciate some aspects of object oriented programming, and in Java8 one can do a lot of really nice stuff that is influenced by functional programming.
Anyway, what I would like from people are a wish list: what would you like the nLab to be/have? If we go for this, I will develop it in an agile way: I will try to get something up and running as soon as possible, and build up the functionality/change things as we go along. Anybody would be welcome to join in. So what I would particularly like for now are a wish list for the fundamental structure of the nLab.
For me, I think we should be making use of a proper version control system, such as git. I envision at least three levels of structure: a git repository, which people can submit things to directly if they wish rather than using the user interface; a visual structure on top of that similar to what we see on the nLab today; and some structure underneath the git repository for organising things. The latter could take many forms: a kind of message logging stream such as Kafka; a more traditional database structure; etc. Probably we would wish for something which reflects the tree-like structure of a wiki.
In the first version, I would probably use only MathJax, with some tweaks as people ask for, and look into adding iTex afterwards if it adds something.
Anyhow, please come with ideas.
Regarding #12: OK, yes, that makes sense. Still, one could change things so that each runs on a different instance; or add an option when creating a web.
I’m not sure exactly what you’re proposing in #13, but I do not think we should try to write our own wiki software! If we want to move away from instiki, we should move to another well-known wiki software with a large user base. We can choose one that allows us to write our own plugins, but we don’t have the resources for large-scale in-house development, which is rarely a good idea anyway.
I understand your reasoning, Mike. But I do mean seriously that I think I could get something up and running which has the basic functionality of instiki, and as good performance if not better, in a very short space of time, as short as it would take me to be comfortable with Ruby on Rails.
Instiki is not really that complicated, from what I have seen of its source code. In particular, I wouldn’t really regard it as a large-scale development. It has only had two or three main developers, for instance.
There are some advantages to whipping up something simple and lightweight from scratch. We do have some particular aspects, with regard to writing mathematics, which will not be reflected in a general purpose wiki. So things like theorem environments, etc, can be basic pieces, rather than things tacked on. And it is much easier to configure something which is simple and built to purpose, than something which is hacked after-the-fact.
It would of course be open-source, etc. And I would keep people here updated step-by-step with the development, so that anybody interested could step in if they wished.
So I don’t think there is much to lose in seeing if I can spin something basic up. If people like it, I can take it further. If not, we are not any worse off.
Referring to #10:
The more I think about it, the more I think the choice should lie with the author, if we want the nLab to be at all citeable.
But there is no one author. (In theory we are bumping up against the same problem where I voiced general discomfort in another thread, over a declaration that one of us wanted to enforce a particular style on certain pages.)
So my latest thinking is that it would be better to come to collective agreement on the numeration scheme now, thinking of all the contributors collectively as “The Author”.
As I said, I don’t like “Theorem 23”. However, if it is to be more like a LaTeX numbering where the items would be enumerated within subsections as mentioned in #11, then I think I’m completely fine with that (and probably wouldn’t even need something different for my own web). I don’t know how others (who haven’t spoken up in this thread) would feel about that scheme, but perhaps we are nearing a mutually satisfactory agreement.
Just a quick note that I hadn’t seen Mike’s #10 before my #11. I share the misgivings about letting the reader choose.
The suggestion of MIke’s for implemention in #10 is nice, and similar to how LaTeX does it. But I do think that if a collective agreement can be reached, as Todd suggests in #17, that would be best.
Sorry if I expressed myself poorly; my objection is not primarily about the effort required, but about the wisdom of in-house development at all.
Many general-purpose wikis have existing plugins for displaying math, and a robust plugin architecture that would make it easy to design things like theorem environments if they don’t already exist. I have some personal experience with TWiki and Semantic MediaWiki. Large developer and user bases mean that bugs – including security holes – can be found by other people and fixed by other people, regardless of whether they surface at a time when you or any of us happens to be busy with something else. And I actually think it is better if features of this sort are plugins rather than “basic pieces”, because it separates their code from the core, helping to ensure the reliability of the latter and that the various features “play well together”. Implementing something as a plugin doesn’t mean it is “hacked after the fact”, it just means it is implemented to conform to a standard for features. I think it’s much easier to configure things that are built to be configurable; custom software tends to have to be “configured” by altering the source code, which in particular depends on having the coder around. I gather you are intending to make a serious committment to the nLab and its software — which is totally awesome by the way!! — but I think we should strive for an architecture in which no single person, or even group of people, is a failure point.
Of course I can’t stop you from doing whatever experiments you want. But I have a really hard time imagining myself ever supporting a move to a custom wiki platform rather than a standard one.
But there is no one author. (In theory we are bumping up against the same problem where I voiced general discomfort in another thread, over a declaration that one of us wanted to enforce a particular style on certain pages.)
Yes, that’s true. I was imagining that it would be like other stylistic choices on the lab, where whoever writes a page originally makes one choice and later authors are expected to adhere to it whatever their personal preferences.
I would be fine with sequential numbering within sections, but I’m not sure at what level of section the numbering should restart. I don’t like triple numbers like “Theorem 7.4.2” — I can live with them in books where “7” is the chapter and “4” the section within the chapter, but in papers that don’t have “chapters” I much prefer only two numbers, like “Theorem 7.12” where “7” is the section. (And I really don’t like quadruple numbers like “Theorem 7.1.2.1”, even in books — I would rather number by chapter and section only, even if it makes some of the numbers larger. For some reason I find “7.2.21” easier to remember than “7.2.4.3”.) Since most nLab pages are significantly shorter than the average research paper (though there are notable exceptions), I would argue for two numbers only. But even then the question is, how many #s means a “section”? On many pages the main sections are labeled with ##, with # for the overall page title, but do we want to incarnate that as the official choice for theorem-numbering?
I imagine two numbers would be fine for many, even most nLab articles. And maybe for all, but I’d like it if we picked a really long article and tested it out there.
I consider headers with two #’s to be sections. I’d be fine for testing it out at that level.
On reflection, I think that you are probably right Mike, thanks! I was thinking of instiki itself when I referred to things being hacked on after the fact, but I agree that a robust plugin mechanism could work well. I do think that there are advantages to building a wiki purposely for mathematics, but I agree that these advantages, unless such a thing were adopted widely or there were several people interested in coding it, seem outweighed by the advantages that you mention of a mature existing wiki with a good plugin mechanism.
Thus I will look into just working with instiki for now. It will take me a little time to get familiar with the codebase, but I should be able to do something within a few weeks.
It looks we are converging to agreement, at least amongst those contributing to the discussion: for sequential numbering of the form Theorem 1.3, where 1 corresponds to sections (##), and 3 corresponds to subsections (###). I agree that it seems unlikely that one should ever need more than that on the nLab; I think it is a good idea not have pages that are too large in any case, so if one feels a need for a ####, one should probably consider breaking things up into several articles.
Excellent! I think there are situations in which a #### is reasonable, but I don’t think they don’t need separate numbers.
of the form Theorem 1.3, where 1 corresponds to sections (##), and 3 corresponds to subsections (###)
Wait, what? I thought the scheme was to be that we enumerate items within a section, so in section 2 we may start with Definition 2.1, followed by Lemma 2.2, Proposition 2.3, Theorem 2.4, Corollary 2.5, etc.
Sorry to be dense, but somebody please explain carefully what the proposal is. If we have two lemmas in the third subsection of the first section, how is it supposed to go?
We do have ####’s on occasion, and reasonably so I believe. I’ve never seen #####.
Sorry, what I wrote made no sense. Yes, I believe that the proposal was for to only have two numbers a.b, where a corresponds to the section, and b corresponds to an environment in that section, regardless of whether b appears in a subsection or a sub-subsection or neither. Both a and b are numbered sequentially.
I’m fine with that. Probably I would prefer to number to subsections myself if they are present., i.e. have a.b.c where a corresponds to section, b corresponds to subsection, and c corresponds to an environment in that subsection. But I can live with having it by section only. Alternatively, could this be something which is decided on a per-page basis?
But I think there is another point to be considered: if we are numbering by sections, or sub-sections, or whatever, then those sections and sub-sections should themselves be numbered in my opinion. So it should say 1 [Title of section 1], or something like that. How would people prefer to punctuate this: just 1, 1., or 1)?
I’m fine with that. Probably I would prefer to number to subsections myself if they are present., i.e. have a.b.c where a corresponds to section, b corresponds to subsection, and c corresponds to an environment in that subsection. But I can live with having it by section only.
I think I could probably go either way, with an a.b scheme or an a.b.c scheme, but maybe we would know better which we prefer after some trial runs.
But I think there is another point to be considered: if we are numbering by sections, or sub-sections, or whatever, then those sections and sub-sections should themselves be numbered in my opinion.
I agree.
Alternatively, could this be something which is decided on a per-page basis?
I think I’d prefer a uniform decision now, if that is possible.
How would people prefer to punctuate this: just 1, 1., or 1)?
Hm, not completely sure. I don’t care for “1)”. I’m pretty sure I don’t like the idea of referring back to “section 1.” or “subsection 1.2.”, i.e., I’d want to refer to “section 1” or “subsection 1.2”. But within the header itself, I might prefer that period there.
Heh, I misread #22 as #25. Yes, I agree that the sections should be numbered, and that in the header they should have periods but not in the references. And, as I said, I think I would prefer numbering to sections only. I’m not sure whether I think subsections should be numbered at all; when environments are numbered by section, I find it a bit confusing to have “Theorem 2.7 … Subsection 2.3 … Theorem 2.8”.
Here is a suggestion for a further tweak: rather than hardcoding a “section” to mean a ## header, define it to be the highest-level header (i.e. fewest #s) of which there is more than one on the page.
OK, great, thanks. Yes, I do not think that subsections should be numbered if they are not part of the environment numbering.
So I think we have arrived at the following proposal: a.b numbering, as in #25, with section titles numbered a. [Section title] but referenced as Section a without a full stop. If anybody has any objections, please raise them!
I would just raise one more point: that the developers of instiki might not wish to merge these changes into the main branch of instiki. In a sense, we would thus be in a similar situation as discussed in #19; on a smaller scale, but one which could become greater over time (it would for instance require some care to merge updates to the main branch of instiki with our custom one). If people have any thoughts on that, please raise them too!
We could probably increase the chances of these changes getting merged into the main branch by implementing them as one or more configuration option that can be turned on or off, and that default to off, so that other installations of instiki would not see any change by default.
We already maintain a significantly forked version of Instiki, available here. Instiki was really only developed with small scale usage in mind, so we’ve had to make several modifications to make it work better for us. I don’t see a problem, though. You could write a patch for Instiki, and I could merge it into our fork independently of whether or not Instiki does.
Thanks Mike, that thought occurred to me too.
But Adeel’s comment probably renders this moot, thanks Adeel! Yes, I have no problem with your suggestion, I was just pointing out that there doesn’t seem to me to be a huge difference between this set up and the writing of something from scratch.
I think maintaining a fork of a widely used piece of software is significantly less problematic than writing and maintaining our own from scratch. However, I would prefer it if our changes could get merged upstream. I’d forgotten (if I knew) that our version of instiki is significantly forked. Have we tried to get our changes merged upstream?
Richard, is there a thread where you taking feature suggestions, as called for in comment #13? (I don't think that this thread should be it, since this thread is about environment numbering.)
Thanks for the interest, Toby! I don’t think that we ever got around to opening such a thread; feel free to do so, I’d be interested to read your thoughts.
Let me take this opportunity to apologise for my lack of activity on this or any other nLab/nForum front. Energy and free time for this have more or less evaporated for the present. I remain willing to contribute, both with mathematics and to Instiki, but it’s difficult to see when an opportunity will arise at the moment. I do keep an eye on the nForum though, so if anybody else becomes interested in this, I’d be happy to try to help out.
As I mentioned once before, feel free to delete/revert the pages on cubical sets that I started. The current state is not satisfactory, but, again, it is difficult at the moment to see when an opportunity will arise to improve matters.
So with all the grand dreams communicated, I’d like to come back to the original idea:
is it easy to change the numbering system of definitions/propositions/theorems? If so, could anyone just implement it? We really need sequential numbering for larger pages.
I am away at the moment, and will be for a couple of weeks more. I will try to find the time to implement this when I come back. Not being familiar with Ruby on Rails slows down what should otherwise be a simple task, as it takes time to get an overview of the code, which I wouldn’t exactly call clear. The basic change that I referred to in #1 is a trivial change to css. But the proposal we settled on, summarised in #28, requires a little more investigation.
Thanks. That trivial change to css, what does it take? If I want to implement this on some page, which code do I have to paste in? Could you tell me?
At the moment, I do not have access to a computer, so it is difficult for me to search through the source code of Instiki (I do not remember exactly where the relevant files are). If you are interested, you could clone the git repo, and search for Theorem or something like that in the source code. This should tell you where the relevant bit of css is. If you let me know here, I’ll see if I can make a suggestion as to how to change the css.
It might also be possible to glean something from the html source of a page, but it appears that this is not so easy on my device either, so I cannot check.
Urs, perhaps the most efficient way to do this is to create a feature request in the instiki git repo, referencing this discussing. Perhaps someone will implement it quickly, or add some suggestions on how to do it.
Bas, in #1 Richard said that this matter is not handled by the instiki software as such, but just by css.
We have our customized css code in the section “stylesheet tweaks” here. This controls for instance the appearance of “query boxes”. From the look of the code, query boxes are the same kind of thing as definition/proposition environments.
So I got the impression that we might just add a few lines to those “stylesheet tweaks”.
Myself, I don’t know what to do, but I am hoping that one of the computer scientists here might be well versed enough to come up with the required edit.
That link was helpful, Urs, it allowed me to locate the relevant file in the instiki source code, which is this one.
The relevant things for theorem numbering begin at line 463. To get sequential numbering, one could just replace all the separate counters by a single one.
It looks like whatever is specified in the nLab page you link to overrides the css file in the source code, so I think your guess is correct, and that if you add something to the nLab css page that is similar to bit in the instiki css file, but with a single counter, then you should obtain the sequential numbering that you are looking for. I don’t know if you can do it per page, though.
Thanks, Richard! I’ll check with Adeel.
I’ve just implemented sequential numbering.
In order for the changes to take effect, I had to reset the cache.
Nice one!
Am I missing something, or is the first change just re-factoring?
There are no unit tests, I guess? (One of the things I’m not overly impressed with in the codebase).
Adeel, I appreciate your efforts, but I thought the thread discussion was converging to an agreement to number by section, so that Theorem 1 in section 3 would be labeled Theorem 3.1 (see comments 20-29).
This is a more non-trivial change, Todd. Urs expressed a wish to change to sequential numbering in the meantime, as this is more or less trivial (just a change in css).
Thanks, Richard. Your usual cheerful and optimistic approach to things had made me believe this wouldn’t be difficult to implement. :-)
Just for my own general education: what is involved in making the change to what we (at least a few of us) had settled on in #28?
44: No, the first change is actually the only part that does anything. Earlier, we had switched to using JavaScript instead of CSS to generate the environment numbering. The CSS changes were just in case we switched back.
45: Sorry, I hadn’t read the whole thread. So in particular, we want to start numbering sections on nLab pages, right? It shouldn’t be too difficult to implement that either, I will try to do it later.
I don’t think it is very difficult, Todd, it just requires, as far as I see, a little more familiarity with the codebase than was needed just making a css tweak; so I myself was not in a position to suggest an immediate fix when Urs asked, I would need a little more time to study the codebase :-)
But happily it seems Adeel has more of an overview, and can see how to do it. In fact, I was only looking at the main instiki repository, for which the css tweak would have been sufficient; the nLab repository, because of the change Adeel referred to of a couple of years ago, needed instead a javascript tweak, which is also pretty trivial once one understands the code.
Thanks, Adeel, I see now (a little comment in the code might aid the non-javascript expert in more quickly understanding what that code is doing, it took me a while :-)).
Adeel, that’s right – and thank you! Very grateful for all your efforts here.
Ok, done.
Excellent!!! Thanks once again, Adeel!
Yay, thanks a bunch!
It looks like the numbered “section”s are hardcoded to mean ## headers. That’s probably fine for the main nLab given our convention that there is always exactly one # header at the top, but it does produce some strange behavior if there are multiple # headers (see my experiment at the Sandbox), which may impact some people’s personal webs. I can’t think of any way to fix that other than something like my suggested tweak in #27 above, which I suppose might be rather hard to implement.
Nice one! When I was originally thinking about this, I wasn’t thinking of doing it ’after the fact’, so to speak, in javascript; to add this kind of javascript customisation on top of the main instiki repo is probably a very good fit for the nLab, well done!
My impression is that your suggestion, Mike, would not be very difficult to implement in a similar style as Adeel has been using; I’m sure Adeel would be able to implement it without much trouble.
It seems that the references still refer to the old numbering, eg. in projective object#EquivalentCharacterizationInAbelianCats, it should say “Proof. of prop. 1.8” instead of “Proof. of prop. 1”
Adeel, thanks a million for this!!
Would it be hard to extend the numbering to include subsections, so that we’d have subsections 2.1 etc. with theorems labeled, say, “2.1-1”. That would make me really happy.
The problem mentioned at #55 is still there. I hope we can fix it!!
1 to 57 of 57