Jupyter header cells ?

[Emmanuel Charpentier]

This question on ask.sagemath.org made me search Google about something called "Header cells". I found such a thing in the Jupyter documentation at Bryn Mawr College.

It seems to me that this is a site-specific extension, not something standard, but I do not know how to find something authoritative about what is "standard" in Jupyter...

It also seems to give some interesting possibilities : cross-referencing, automatic numbering, auto-table of contents.

Do you think that this (or something like this) could be useful in our Jupyter notebook ?

--

Emmanuel Charpentier

[Erik Bray]

On Tue, Dec 26, 2017 at 5:27 PM, Emmanuel Charpentier
<emanuel.c...@gmail.com> wrote:
> This question on ask.sagemath.org made me search Google about something
> called "Header cells". I found such a thing in the Jupyter documentation at
> Bryn Mawr College.
>
> It seems to me that this is a site-specific extension, not something
> standard, but I do not know how to find something authoritative about what
> is "standard" in Jupyter...

I'm not sure what you mean. Header cells are a normal part of the
notebook. As the name suggests it's just a special cell type for
section headers in the notebook. You can also make headers by making
a normal markdown cell and putting in markdown-formatted headers, but
I think the point of header cells is that they are more inherently
part of the structure of the notebook itself, independent of the types
of cells following the header. So the header cell can be moved around
relative to other cells and the notebook can keep track of it as part
of its structure, if that makes sense.

> It also seems to give some interesting possibilities : cross-referencing,
> automatic numbering, auto-table of contents.
>
> Do you think that this (or something like this) could be useful in our
> Jupyter notebook ?

You could do this in any Jupyter notebook I think.

Best,
Erik

[Emmanuel Charpentier]

The documentation I referenced shows the presence of specific tools in their implementation (specialized buttons, menus items, etc...) that seem to be necessary for cross-referencing and auto-TOC. The "Header cells" seem to be distinct from Markdown cells, code cells and raw cells.

As far as I can tell, this is not available in "our" Jupyter.

I'm not sanguine about this enhancement :

• It certainly can be useful for heavy Jupyter users.
  
• OTOH, it is also a form of "LaTeX envy"...
  

I see more and more proposals to add LaTeX-like features to Markdown (such as citation management, cross-referencing, indexing,....). But Markdown was not created to be a LaTeX replacement, and these various proposals are problem-specific kludges, mutually inconsistent and, IMNSHO, not up to the standard proposed by LaTeX.

I see these "enhancements" as a way to avoid the Matterhorn-like learnng curve of LaTeX ; but I think that, in the long term, the larger investment on LaTeX yelds a better ROI. The key point is, of course "in the long term" : someone not planning to  publish extensively might use Jupyter as a way to meet a specific, one-time requirement (e. g. graduating) ; however, someone planing to have to publish more than once or twice is probably better off learning LaTeX which, as a scientific document preparation system, has not yet been superseded (after about 30 years... !).

In other words, "heavy Jupyter use" is a bit of an oxymoron in my eyes (or, at least, a misguided choice).But I might be missing a point, hence my question.

--

Emmanuel Charpentier

[Erik Bray]

On Wed, Jan 3, 2018 at 2:47 PM, Emmanuel Charpentier
<emanuel.c...@gmail.com> wrote:
> The documentation I referenced shows the presence of specific tools in their
> implementation (specialized buttons, menus items, etc...) that seem to be
> necessary for cross-referencing and auto-TOC. The "Header cells" seem to be
> distinct from Markdown cells, code cells and raw cells.
>
> As far as I can tell, this is not available in "our" Jupyter.

I'll have to take a closer look, but I'm still confused because
"header cells" have been in the notebook going way back (since early
versions of IPython Notebook). The cross-referencing and TOC stuff
I'm less sure about.

> I'm not sanguine about this enhancement :
>
> It certainly can be useful for heavy Jupyter users.
> OTOH, it is also a form of "LaTeX envy"...
>
> I see more and more proposals to add LaTeX-like features to Markdown (such
> as citation management, cross-referencing, indexing,....). But Markdown was
> not created to be a LaTeX replacement, and these various proposals are
> problem-specific kludges, mutually inconsistent and, IMNSHO, not up to the
> standard proposed by LaTeX.
>
> I see these "enhancements" as a way to avoid the Matterhorn-like learnng
> curve of LaTeX ; but I think that, in the long term, the larger investment
> on LaTeX yelds a better ROI. The key point is, of course "in the long term"
> : someone not planning to publish extensively might use Jupyter as a way to
> meet a specific, one-time requirement (e. g. graduating) ; however, someone
> planing to have to publish more than once or twice is probably better off
> learning LaTeX which, as a scientific document preparation system, has not
> yet been superseded (after about 30 years... !).

I agree with all in theory. Though as I once learned, in an
embarrassing manner, one of the first times I taught Software
Carpentry to an audience that was not just astronomers/physicists,
outside those fields and mathematics LaTeX is *not* de facto.

Yes, maybe scientists in life science, social science, etc. should
also learn LaTeX but for many of those fields it's not nearly as
common and there's maybe far less ROI there.

> In other words, "heavy Jupyter use" is a bit of an oxymoron in my eyes (or,
> at least, a misguided choice).But I might be missing a point, hence my
> question.

Maybe, but it's a whole new world...

Best,
E

> --
> You received this message because you are subscribed to the Google Groups
> "sage-devel" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to sage-devel+...@googlegroups.com.
> To post to this group, send email to sage-...@googlegroups.com.
> Visit this group at https://groups.google.com/group/sage-devel.
> For more options, visit https://groups.google.com/d/optout.

[Dima Pasechnik]

Considering that Apple added a quite complete LaTeX support to Pages (their presentations editor)

and iBooks Author (e-books writing tool) we'll hopefully see a wider use of LaTeX

soon...

[Jason Grout]

Header cells in Jupyter notebooks have been around a very long time (since essentially the beginning?). Years ago there was talk of deprecating them in lieu of just using Markdown header syntax in markdown cells. There aren't officially supported TOC or section-structuring features in the notebook. We may see more section-structuring features in the notebook going forward, though I don't know of anyone that has definite plans to work on it right now.

You can convert a notebook to tex using nbconvert, and you can even write latex in the notebook "raw" cells and have it output as part of the latex in a conversion. And there's no technical problem that I know if in doing something like sagetex using Jupyter kernels to give you the computation engine of Jupyter inside of TeX.

What version of the Jupyter notebook is in Sage? I'd be surprised if it didn't have header cells.

Jason

[Samuel Lelievre]

Sat 2018-01-06 15:57:42 UTC, Jason Grout:

>
> What version of the Jupyter notebook is in Sage?

> I'd be surprised if it didn't have header cells.
>
> Jason

In Sage 8.1:

    $ cd /path/to/sage-8.1/upstream
    $ ls | grep jup
    jupyter_client-5.1.0.tar.gz
    jupyter_core-4.3.0.tar.gz

In Sage 8.2.beta0:

    $ cd /path/to/sage-8.2.beta0/upstream
    $ ls | grep jup
    jupyter_client-5.1.0.tar.gz
    jupyter_core-4.4.0.tar.gz 

[Jason Grout]

Thanks. The Jupyter notebook is in the "notebook" pip package.

Jason

[Samuel Lelièvre]

Sage 8.1 has notebook 4.4.1, while Sage 8.2.beta0 up to Sage 8.2.beta1 have notebook 5.2.1.

$ ls /path/to/sage-8.1/upstream | grep notebook

notebook-4.4.1.tar.gz

$ ls /path/to/sage-8.beta0/upstream | grep notebook

notebook-5.2.1.tar.gz

$ ls /path/to/sage-8.beta2/upstream | grep notebook

notebook-5.2.1.tar.gz

[Jason Grout]

Cool, thanks, good to see things are getting up to date. Both of those definitely have the concept of header cells.

Jason

[Samuel Lelièvre]

Yet the attached screenshot seems to indicate that

the Jupyter notebook server launched by SageMath

does not include selecting the "Header" cell type.

Is there some configuration mechanism for deciding

which cell types are offered, which maybe would need

to be set up differently?

Samuel

> You received this message because you are subscribed to a topic in the Google Groups "sage-devel" group.
> To unsubscribe from this topic, visit https://groups.google.com/d/topic/sage-devel/Pn2nAPSuGig/unsubscribe.
> To unsubscribe from this group and all its topics, send an email to sage-devel+...@googlegroups.com.

[Emmanuel Charpentier]

Le samedi 6 janvier 2018 22:10:46 UTC+1, Samuel Lelievre a écrit :

Yet the attached screenshot seems to indicate that

the Jupyter notebook server launched by SageMath

does not include selecting the "Header" cell type.

Indeed. It's this difference between our notebook and the documentation found at Brywn Mawr College that led me to conclude that header cells were something different from Markdows cells containing headers.

I haven't been able to find other references to those headers cells...  A slightly wider search tells me that "Heading cells have been removed in IPython 3". A similar feature has been developed for Jupyter 2.x to 4.x (documented here).

So the question may boil down to : does the feature alluded to by the original ask.sagemath.com question is

• a standard feature we miss somehow,
  
• a former, deprecated  feature , or
  
• an unofficial extension, which turns out to be documented as standard at Brywn Mawr College ?
  

and begets another question : should we add it to "our" notebook ?

--

Emmanuel Charpentier

 

Is there some configuration mechanism for deciding

[Jason Grout]

I looked more into it. I was wrong (or more correctly, I was outdated). Indeed, recent versions of the notebook over the last while (years?) *have* deprecated the header cells, and they have been removed from the notebook format, I think since at least notebook format 4.0 in 2015 or so:

https://nbformat.readthedocs.io/en/latest/format_description.html#markdown-cells

"Heading cells have been removed, in favor of simple headings in markdown."

The shortcut commands that also used to exist now just insert markdown cells with the appropriate header text (i.e., pressing '1', '2', etc.).

Jason

[danielv...@yahoo.es]

Since I was the originator of this request I would like to explain myself.

I'm new to SageMath, but I have been using WxMaxima for quite a while now.

I would like to have some way to define Sections and Subsections in a SageMath notebook, but the definitions should not be static, i.e. if I define 1, 2, 3, 4 sections in my document and then I delete Section 2, I want section 3 to be renumbered 2 and section 4 to be renumbered 3 so that the section numbers are always consecutive. If I then add a section in the middle between 2 and 3 I want it to be numbered 3 and section 3 to be renumbered 4.

The same for subsections inside a section. They should always be numbered consecutively no matter how many times I delete or add subsections. 

Long term, I would like to be able to create a PDF file from this notebook with those section and subsections as bookmarks of the file so I can access then using the bookmark PDF panel.

Thanks,

Daniel

[Emmanuel Charpentier]

Dear Daniel,

Le vendredi 19 janvier 2018 21:05:59 UTC+1, danielv...@yahoo.es a écrit :

Since I was the originator of this request I would like to explain myself.

I'm new to SageMath, but I have been using WxMaxima for quite a while now.

Which is indeed a good notebook (if a bit insular, when compared to the Jupyter ecosystem).

I would like to have some way to define Sections and Subsections in a SageMath notebook, but the definitions should not be static, i.e. if I define 1, 2, 3, 4 sections in my document and then I delete Section 2, I want section 3 to be renumbered 2 and section 4 to be renumbered 3 so that the section numbers are always consecutive. If I then add a section in the middle between 2 and 3 I want it to be numbered 3 and section 3 to be renumbered 4.

The same for subsections inside a section. They should always be numbered consecutively no matter how many times I delete or add subsections. 

It turns out (see previous posts in this thread) that the feature you were searching for has been removed from modern versions of Jupyter ; users are now supposed to make-do with Markdown's headers.

The Jupyter developers propose some extensions that may or may not fulfill your needs. I have no idea how easy (or hard) it would be to add (some of) them to the current Sage Jupyter notebook.
 

Long term, I would like to be able to create a PDF file from this notebook with those section and subsections as bookmarks of the file so I can access then using the bookmark PDF panel.

[ Full disclosure : I was first exposed to emacs and LaTeX 31 years ago ; my professionnal life has made me endure various "word processors" and suchlike horrors for more than a quarter century . I can hardly claim unbiasedness... ]

I am often confronted to this conudrum. I find the Sage notebook extremely handy to jot down an idea, toy and experiment with it and take quick notes, but I feel more at home with LaTeX when it comes to writing down things for good.

LaTeX has been created to prepare structured documents. It supports not only hierarchical sectioning, but also cross-referencing, footnotes, tables of contents,  indexing, references (most important !), und so weider ad infinitum... SageTeX is a LaTeX package that allows to insert almost any form of Sage calls in a LaTeX document, from the simple inline insertion of a Sage expression to a full program, along with LaTeX documentation.

The development of such a document is tremendously helped by the use of emacs along with sage_shell_mode, which allows you to run Sage in an emacs frame, allowing you to check your (typeset) results and your (2D) figures ; it even has a notebook emulation feature that might help your transition.

The price to pay is learning these tools, of course. Emacs' learning curve is a bit Matterhorn-like (only a bit steeper, according to some...), Latex's vastness can be compared to the Ural, and sage is ... well... Sage (and expanding !). But these difficulties are mutually healing : emacs' infinite programmability opens the possibility of sage_shel_mode, but also of AUCTeX and RefTeX (which make the maintainance of a complicated document a breeze, compared to what word processors offer) and allow you not to learn 90% of LaTeX (the existing macroes will do the job for you).

However, almost all you need for that *can* be done in Markdowwn. It just happents that these tools exist in a zillion different (and mutually incompatible, of course) extensions, with no central federating program.

Furthermore, these tools are probably better adapted to the production of "dynamic" documents such as HTML pages or e-books, whereas LaTeX is strongly paper-oriented : papers, books, slides are supposed to have a *fixed* layout.

If you aim to go to the Web or e-publications (such as e-pub), you might be better off developing your document in the Notebook, exporting to pandoc or something like that, and re-exporting to HTML, e-pub or whatever (my experiences of converting a math-heavy LaTeX document to epub was not, to say the least, overwhelmingly successfull : the solution lies probably somewhere in the futire of LaTeXML). That way, you could ask Pandoc to number your section hierarchy and insert a table of contents. I currently see no way to cross-refer your document in the notebook (but I'm certainly not an expert in Markdown), but it might be added in this post-processing stage.

So pick your poison according to your goals : if you aimt to a PDF, LaTeX is perfect, and learning to use it with the help of AUCTeX and sage_shell_mode might well worth learning emacs. If you aim to e-publication, pandoc is worth a look.

HTH,

Emmanuel Charpentier

Thanks,

Daniel

[Samuel Lelièvre]

For generating books mixing LaTeX and computation cells,

see also PreTeXt:

    http://mathbook.pugetsound.edu/

​

[danielv...@yahoo.es]

Hi All

 

How do I obtain automatic numbering of sections and subsections, as described above, with Markdown?

Thanks. 

 

​