# Start a new discussion

## Not signed in

Want to take part in these discussions? Sign in if you have an account, or apply for one below

## Site Tag Cloud

Vanilla 1.1.10 is a product of Lussumo. More Information: Documentation, Community Support.

• CommentRowNumber1.
• CommentAuthorMike Shulman
• CommentTimeAug 2nd 2016

After thinking it over some more, here is a proposal for a convention about page length and sub-pages that I think would make me fairly happy and might also be acceptable to others (perhaps with further tweaking). It’s just an idea; please criticize it — constructively, if possible; but if not, you can do it classically. ;-)

The main organizational units of the nLab would continue to be “main” pages about concepts, generally named after mathematical nouns, as is currently the case. These pages would continue to have sections (## level) such as Idea, Definition, Examples, Related Pages, References, and others that are more flexible in the middle like Properties or Main Theorem. However, I propose two new guidelines regarding such pages:

1. They are written for an audience of research mathematicians (i.e. graduate school and up) having some familiarity with other related subjects and with the nPOV (though of course hyperlinks continue to be provided).
2. No section should be longer than a handful of paragraphs, contain more than a couple theorems, or have more than 2-3 subsections; nor should there be more than a couple sections other than the standard ones, and sub-sub-sections (#### level) are discouraged altogether.

The material that is excluded by these guidelines goes on sub-pages having a uniform naming scheme, ideally indicating not just the main page that they belong to but the section of it that they are an expansion of. So, for instance, we might have a page called “semigroup/Definition - historical notes” (as one possibility). Links to these pages are placed in the appropriate section of the main page, along with a brief summary of their content. Moreover, at the top of such sub-pages there should be a “breadcrumb” hatnote linking to the main page that they belong to.

The content of sub-pages is less restricted than that of main pages, and may depend on the purpose of the sub-page. For instance, a hypothetical sub-page “infinity-category/Idea - for novices” might be written in a very chatty style with lots of pictures and not much organization, while a hypothetical sub-page “(infinity,1)-category/Definitions - web of Quillen equivalences” might be organized with one section for each Quillen equivalence between a pair of definitions and each section potentially quite lengthy in definition-theorem-proof style. I suppose sub-pages could even have sub-pages, but the naming conventions would get less wieldy.

I’m inclined to discourage linking directly to sub-pages (and, by extension, adding redirects to sub-pages), because such links would break if we decided to reorganize the division of a page into sub-pages. However, I could be convinced otherwise.

There is one further enhancement to this proposal that I think would make it much more reader-friendly, but would require a bit of coding to achieve: transclude the sub-pages into the main page as knowls. I’m imagining a new link syntax for instiki, such as {{page name}}, that would create a knowl rather than a link — or, even better, a knowl and a link (maybe the page name itself is a knowl, while after it there is a small icon that serves as a link), since otherwise there would be no easy way to edit the sub-page. Moreover, we would probably want some sort of syntax for the sub-pages allowing us to exclude parts of them upon transclusion (such as the title and breadcrumb links), like mediawiki’s noinclude and includeonly.

Thoughts?

• CommentRowNumber2.
• CommentAuthorTodd_Trimble
• CommentTimeAug 2nd 2016

If we could take a fairly long current page, maybe with sub-sub(-sub)sections, and see how these proposals might play out by fiddling with that page, it might help us (or me, anyway) see what is involved and what is at stake. But some people have worked hard on certain pages and might be upset to have much fiddling done to them, having their work undone in some sense.

(I could try to locate a page with a heavy “Todd thumbprint” and nominate such a page for fiddling.)

“Knowls” is a cool idea. Can you embed them, i.e., have subknowls?

• CommentRowNumber3.
• CommentAuthorMike Shulman
• CommentTimeAug 2nd 2016

We could copy such a page to doriath to fiddle around with. Yes, you can have subknowls.

• CommentRowNumber4.
• CommentAuthorDexter Chua
• CommentTimeAug 3rd 2016
• (edited Aug 3rd 2016)

I’m not very keen on having length limits (or “guidelines”) for sections - if some ideas need long expositions to motivate properly, let it be. Instead, we should “hide things away” in subpages if they tend to obscure the big picture.

This is rather vague, but I think the three examples listed in #1 would be good examples of things we would like to “hide away”. On the other hand, if we have 10 different ways of motivating the idea of a topos, I don’t see why we shouldn’t be presenting all of them in the main page.

The general idea would be that the content in the main page would be what one would want to have a good overview of the subject if they learn about it for the first time, including the relevant motivations, definitions, important properties and examples. So certain important theorems might be stated with a brief outline of proof, and detailed proofs would fit into separate subpages.

How would section and theorem numberings work with knowls?

• CommentRowNumber5.
• CommentAuthorMike Shulman
• CommentTimeAug 3rd 2016

I wouldn’t think that 10 different ways of motivating the idea of a topos would be “what one would want to have a good overview of the subject if they learn about it for the first time”. For an overview it should suffice to sketch the most important motivations and link to a sub-page for the others; anything more I would consider to obscure the big picture.

I also realized that section and theorem numberings would get all messed up with knowls if done naively. Bah. I don’t even know what the behavior should be in a situation like that.

• CommentRowNumber6.
• CommentAuthorDexter Chua
• CommentTimeAug 3rd 2016

Okay I agree 10 motivations would be too much, but if it takes 10 paragraphs to explain a motivation, I think that would be okay.

A page where sub-pages are already used is sigma-model#ExpositionClassical, and I quite like how it is presented there. For long subpages like that, I think I will prefer being sent to a separate entry than the content being included in a huge knowl.

On the other hand, I think useful application of knowls would be for recalling some definitions or theorems from other pages. For example, when a theorem talks about full and faithful functors, instead of linking people to the relevant page, clicking on it would give a transclusion of the definition, plus a link to the full and faithful functor page.

A possible syntax for indicating a transcludable section would be

+-- {: .transclude #Definition}
+-- {: .num_defn}
###### Definition
A **full and faithful functor** is a [[functor]] which is both [[full functor|full]] and [[faithful functor|faithful]].  "Full and faithful" is sometimes shortened to "fully faithful" or "ff."   See also [[full subcategory]].
=--
=--


And then we can refer to the definition by

Let $F: C \to D$ be a {{full and faithful#Definition|full and faithful}} functor...


In this case, the trasncluded definition could be numbered according to the original page, for easy reference, or it could be not numbered at all.

One problem I could imagine is that it would be difficult to find the right place for the knowl to pop up, if we are linking to it from the middle of a paragraph, whereas it is clear what to do if we are including a subpage.

• CommentRowNumber7.
• CommentAuthorMike Shulman
• CommentTimeAug 3rd 2016

I think 10 paragraphs of motivation is at least sometimes too much for an overview, but I’m willing to be flexible. The page sigma-model is a good example, and pretty close to the proposal already. I would prefer that the Idea section be a little more concise, but that’s a matter of personal taste. I would also like it if sections 3-5 could include a paragraph or two summarizing the content of the sub-page.

I also would sometimes prefer going to a separate page rather than opening a knowl. My proposal, if we could implement it, would allow the user to choose which: each knowl would have both something to click on to open it as a knowl and also something to click on to go directly to the page.

Transcluding individual sections or definitions is a neat idea. I think with a knowl you don’t have to “decide” where it’s going to pop up; the javascript code automatically puts it at the end of the containing HTML element (usually a <p>).

• CommentRowNumber8.
• CommentAuthorDexter Chua
• CommentTimeAug 3rd 2016

Transcluding individual sections or definitions is a neat idea. I think with a knowl you don’t have to “decide” where it’s going to pop up; the javascript code automatically puts it at the end of the containing HTML element (usually a <p>).

I’m not sure we would always want that to happen, though. For example, it is not uncommon to have things like

Something something knowl something

$\text{A display equation}$

Something something

and we might not want the knowl to appear between the first line and the equation.

• CommentRowNumber9.
• CommentAuthorMike Shulman
• CommentTimeAug 3rd 2016

I don’t know whether it’s possible to control the location popup of knowls manually. I don’t think it’s a big deal if they pop up before a displayed equation; ones that appear in text are going to be fairly short, and the reader can just read them and then close them again before going on.

• CommentRowNumber10.
• CommentAuthorRodMcGuire
• CommentTimeAug 3rd 2016

Rather that the somewhat complicated “knowls” and transclusion for stuff Mike doesn’t want to look and is really are a different issue how about just having section headers be clickable to hide or display their content.

I for example when looking at a page on some structure where I just want to get the basic idea am not interested in Proofs and often have to scroll over them to get the gist. For this purpose having proofs suppressed would make the page more readable.

A better “knowl” like application would be say give all pages brief knowl summaries so that when I’m reading something that mentions say “relective subcategory” I can click on it and get the summary inlined on the current page rather than having to visit the whole page for that topic.

The use of knowls in the example page aimath.org/knowlepedia/ is more about inlining short definitions rather suppressing large content sections.

From the mentioned Linear Algebra text book see this page: Arithmetic with complex numbers. There knowls are used to suppress examples and proofs. They are also used to inline brief summaries of things discussed elsewhere - e.g. (Proof Technique E), (Proof Technique CP), Theorem NPNT.

• CommentRowNumber11.
• CommentAuthorDexter Chua
• CommentTimeAug 4th 2016
• (edited Aug 4th 2016)

One example of Very Long Pages I’ve recently come across is cohomology. I think this would be a good example of something we would want to break down. Urs appears to be the main contributor to the page based on a quick scan.

• CommentRowNumber12.
• CommentAuthorMike Shulman
• CommentTimeAug 4th 2016

@Rod, that would achieve some of the same effect on the user end, but I had the impression that some people (for editing purposes, at least) wanted the actual page text not to be so long. I don’t think there’s anything wrong with using a technology for anything it can do, even if it isn’t how other people are using it. But if hidable section headers would be easier to implement, we could certainly try them out!

• CommentRowNumber13.
• CommentAuthorzskoda
• CommentTimeAug 4th 2016
• (edited Aug 4th 2016)

I appologize for being behind in this discussion (partly initiated by my complaints). Thank you for the efforts, I will catch up soon (I do not yet comprehend the above proposals sufficiently well to contribute).

• CommentRowNumber14.
• CommentAuthorTobyBartels
• CommentTimeAug 27th 2016

I like hideable section headers. But I also like not getting 504 Gateway Time-out, so I like limiting the lengths of pages too, at least for now.