Jupyterbook: enable citations/references about doconce HOT 9 CLOSED

[..] if these changes are implemented citations, in DocOnce files seem to work properly [..]

I am not sure I understand your request.

Citations and their bibliography seem to work using jupyter-book's syntax. Do we want to implement them using DocOnce's syntax?

from doconce.

Sorry for the sloppy wording. What I meant was, when I do this:

• convert a DocOnce file using the doconce format jupyterbook command
• in the resulting markdown and ipynb files, change [@...] citations to the corresponding cite ones
• instead of a bibliography add the {bibliography} thingy
• compile to a jupyterbook with jupyterbook build

This gives a properly rendered bibliography and citations. That was meant to argue for that implementing this should be relatively straightforward (he said optimistically)...

from doconce.

I will probably try the approach similar to the one described in the previous comment, i.e. converting citations and bibliography from DocOnce to jupyter-book's syntax, then let jupyter-book create the html documents. Notice that in this case a user should add a bibtex_bibfiles: entry to _config.yml.

I am currently trying a different approach: preserve the bibliography created using doconce format html, which IMO is nicer than jupyter-book's. While trying this I encountered issue #98 (links still refer to the their own html document, which is not always right).

from doconce.

To reproduce:

## mybook.do.txt
TITLE: Input file for doconce jupyterbook
AUTHOR: Alessandro Marin
AUTHOR: Alessandro Marin again
TOC: on
DATE: today

======= Chapter 1 =======

Testing citations/references using __DocOnce__'s syntax. The references were converted from `*.bib` to `*.pub` using Publish:
`publish import papers.pub`

Citation using `cite` `[]{}`: cite[Some Detail]{Langtangen_Pedersen_2002}

Another citation using `cite` `{}`: cite{Langtangen_et_al_2002}

Reference `ref` `{}` to section ref{ref:test:label} below.


===== Section 1 =====

Two citations using `cite` `{}`: cite{Langtangen_Pedersen_2002}, cite{Langtangen_et_al_2002}

Reference `ref` `{}` to section ref{ref:test:label} below.

===== Section 2 =====

Three citations using `cite` `{}`: cite{Langtangen_Pedersen_2002}, cite{Langtangen_et_al_2002}, cite{Langtangen_Pedersen_2002},

!bc pycod 
1+1
!ec



======= References =======

This is the bibliography

A label: label{ref:test:label}

BIBFILE: ../papers.pub

Commands:

cd test
jupyter-book create mybook
cd mybook
mkdir content

doconce jupyterbook mybook.do.txt --sep=section --dest=content --dest_toc='.' --allow_refs_to_external_docs
jupyter-book build .

Publish file with references test/papers.pub:

* articles
** Propagation of Large Destructive Waves
   key:       Langtangen_Pedersen_2002
   author:    H. P. Langtangen, G. Pedersen
   year:      2002
   journal:   International Journal of Applied Mechanics and Engineering
   volume:    7
   number:    1
   pages:     187-204
   status:    published
   entrytype: article
** Numerical Methods for Incompressible Viscous Flow
   key:       Langtangen_et_al_2002
   author:    H. P. Langtangen, K.-A. Mardal, R. Winther
   year:      2002
   journal:   Advances in Water Resources
   volume:    25
   pages:     1125-1146
   status:    published
   entrytype: article

from doconce.

@lexnederbragt Please check this out. As I wrote before I am going for DocOnce's bibliography stile instead of juyter-book's. Let me know if it is ok

from doconce.

It looks OK for bibliographic references and the bibliography. I've tested your example and the 'book' that I am working on. this is great!

There is one issue with making a reference to a section. Normally, label{ref:test:label} would be placed directly under the section header, in this case ======= References =======. Then to section ref{ref:test:label} below. becomes section References below. with References a hyperlink to the correct session. You can see this by placing the label below the section header in my book.do.txt converting to html.

With DocOnce jupyterbook, the link to the section becomes to the section ref:test:label below. with ref:test:label a hyperlink to the correct section.

A label that is referenced in the same markdown file created by doconce jupyterbook gets the correct section heading name.

from doconce.

https://doconce.github.io/doconce/doc/pub/manual/manual.html#___sec53:

When the label is placed after a section or subsection heading, the plain text, epytext, and st formats will simply replace the reference by the title of the (sub)section.

from doconce.

This last problem is due to the fact that doconce jupyterbook splits the DocOnce file in chapter/sections and then applies doconce format pandoc|ipynb to each of them. The ref in your example is not "aware" of its corresponding label, because it is present in a different documents.

I am afraid there could be other problems where the jupyter-book is not the same as when formatting to e.g. html. For this reason I am revisiting the implementation of doconce jupyterbook, where I mark the DocOnce input where it should be split, then format it to both pandoc and ipynb, and then split the outputs.

So far it seems to work but I will have to carry out tests to avoid errors.

from doconce.

I think this issue can be closed...?

from doconce.