FYI: basic reqs for academic documents

1

Hey again, we discussed this a little bit at the meetup. Some of this can be programmed outside and on top of prosemirror (by running several instances of PM on the same webpage). For the inline elements my idea was to simply have PM drop a non-editable “custom element” a certain place in the DOM and use our own editor for editing those elements apart from PM. Editing of such elements (citations or figures) would happen when the user clicks on one of the elements.

Nevertheless, I thought it would likely be interesting for you to see all the things used in a basic academic article, even though a lot of this can be dealt with outside of ProseMirror.

Btw, these are the needed elements according to our research. There may be other elements that other scientific communities believe are essential. And it is assuming that tables are so hard to deal with that there is no point to even trying to handle them inside the editor. Instead users are forced to embed tables as SVGs.

Document parts

  • Title (required)
  • Subtitle (optional)
  • Authors (optional)
  • Abstract (optional)
  • Keywords (optional)
  • Article body (required)
  • Bibliography (optional, auto generated if used)

Block level elements for textual contents

  • P
  • H1-H3
  • Blockquote
  • Code
  • UL/OL

Inline level styling

  • Strong
  • Emphasized

Inline text elements

  • Links (standard HTML links)
  • Footnotes (Have to be displayed off to the side or below the text, and need to be able to contain all the things that body elements can contain)

Non-editable block level elements

  • Figures with following sub elements:
    • Figure content: an image, a math formula or an SVG (required)
    • A figure category (fx “Figure”, “Photo”, “Table”) (optional)
    • An automatic figure number (optional)
    • A caption (optional)

Non-editable inline elements

  • Citations with the following fields (for humanities where citations may look this way: “If a stone sinks in water, it is likely a heavy (See for example: Newton 1687, pages 1-5).”):
    • reference source ID (fx a specific book, a small database in a client side database keeps track of all the different sources the user may use)
    • reference pointer (fx a page number)
    • type of reference pointer( fx “page”, “pages”, “paragraph”)
    • text before citation (fx “See for example:”, “Also mentioned in:”, etc.)
  • Inline math formulas
  • References to figures in the same text (fx: “See figure 4” . where the “4” has to be updated when the figure numbering changes).
1 Like
2

Thanks for the list! I’ll keep these in mind.

3

Ooh, this is neat! I definitely think sidenotes/footnotes/endnotes are still an unsolved problem on the web, although Medium and Google Docs’ implementations both provide interesting perspectives on this.

How do academics write mathematical notation and draw figures, usually? I presume something like LaTeX (exported to SVG? or perhaps HTML?). Are mathematical formulae usually inline, or in a separate figure? (I believe I’ve seen both, in my limited experience of academic papers)

4

The simplest acceptable version, according to our findings, is to let the user enter math formulas using LaTeX (and then use mathjax or equivalent to make them look good). But for more complex figures to force them to create an image or an SVG of it. If users get to choose one more figure type they want to be able to edit through the web editor, the answer is usually tables.

yes, both. Both depends a bit on what the formula is used for. We have listed them both places.

2 Likes