An Extendable Essay on the Sage Computer Algebra System and an Editor for Creating Extendable Essays

Abstract

An extendable essay is a special format of electronic texts that is more convenient for reading than hypertext. To facilitate the creation and editing of extendable essays, an editor program implemented as a web application is proposed. Using this editor, an extendable essay on the Sage computer algebra system is written. Sage seems to be a good choice for the users who are not familiar with computer algebra systems.

INTRODUCTION

Nowadays, people more often deal with electronic texts than with texts printed on paper. The number of electronic texts is growing like an avalanche.

Since the 1980s, differences in the physiological and cognitive perception of paper texts and electronic texts have been analyzed. Researchers have been interested in various aspects of electronic texts, including the influence of their physical characteristics (e.g., the brightness and color of the screen, text layout, font style, etc.) and their structural properties (division into logical fragments, size of displayed fragments, etc.) on the reader. Scientists have not yet come to clear answers to all questions; however, some conclusions are accepted by the scientific community. The review [1] states: “An electronic text as an object of reading indeed has a number of features that affect the psychological processes of reading.” Some studies find that, when reading electronic texts (in contrast to paper texts), the reader experiences a decrease in reading speed, increase in cognitive workload, and decrease in reading accuracy (attention) (see [1]).

It should be noted that the processes involved in reading linear electronic text are different from those involved in reading hypertext. In [2], it was shown that the presence of links increases the mental workload in two ways: directly, when the reader decides to follow a link, and at a higher level of understanding the text (clicking on links breaks the connection between parts of the text and causes the loss of its integral perception). The form of electronic text organization described below is developed to make it easier for the reader to maintain the integrity of text perception.

In [3], a scheme for organizing texts in the form of extendable essays was proposed. An extendable essay is a brief representation of a text material (educational, scientific, or informative) with optional extensions, which supplement the basic text with explanations, illustrations, examples, and references. To the reader, an extendable essay initially looks like a regular text with the traditional division into sections and paragraphs. Some paragraphs have special icons indicating that the paragraph can be “extended.” If the reader clicks on the extend icon, then the paragraph is replaced with a longer paragraph or several paragraphs. Thus, while reading, the reader can customize the text by choosing a brief or detailed representation of the material depending on his or her needs. The fundamental difference between the extendable essay and the hypertext is that, with any extension, the text of the essay preserves its integrity and coherence. This allows us to hope that modifying the text in the process of reading will not create inconvenience to the reader.

STRUCTURE OF AN EXTENDABLE ESSAY

The format of extendable essays was developed primarily for organizing educational materials, which underlies its specific features [3].

An extendable essay is similar to a regular book: it has a title, an author, and text itself. The text is divided into sections, which consist of paragraphs. Each paragraph can have an extension (a more detailed version), in which case there is an extend icon on the left-hand margin of the paragraph. A section can end with test questions.

The text of an extension is structurally a paragraph or several paragraphs, each of which can also have extensions (so to speak, extensions of the second, third, etc. levels). Thus, the extendable essay has a linear hierarchical structure. The depth of extension nesting is formally unlimited. However, experience suggests that there is no need in more than two levels; otherwise, the essay becomes uncomfortable to read because of a strong contrast in the number of details between the basic (non-extended) text of the essay and its maximally extended text.

There are several types of extensions, each of which has its own icon:

“+” is a detailed explanation;

“:” is an example;

“[ ]” is a reference;

“T” is a question or test.

If the reader opens a paragraph extension and decides that the short version of the paragraph is sufficient for understanding, then the reader can close the extension by clicking on the icon on the left of the extension to return to the basic (short) version of the paragraph. Figures 1 and 2 show the non-extended and extended fragments of the essay, respectively.

Fig. 1. [Images not available. See PDF.]

Fragment of the essay with a closed extension.

Fig. 2. [Images not available. See PDF.]

Fragment of the essay with an opened extension.

The “T” extension is different from extensions of other types: it allows the reader to test him- or herself. When the reader clicks on the “T” icon, a question appears with several answers to choose from. Upon selecting an answer, the reader is provided with the correct answer and an explanation for it. The essay writer can prepare several questions for a section. In this case, the question presented to the reader is selected randomly from a list of questions.

CREATION OF EXTENDABLE ESSAYS

Since the format of extendable essays requires different levels of detail, the writer must determine which fragments need to be explained in more detail (i.e., extended). Then, it is required to write more than one complete text on the topic of the essay; for some fragments, several variants are needed: the basic text and the extension. Finally, it is necessary to check that the essay is read smoothly with any combination of fragments of the basic text and extensions.

In [3], an extendable essay was implemented as an HTML file in such a way that the reader can open and read the essay by using a web browser. Interactivity (showing and hiding extensions) is provided by JavaScript. If the essay contains illustrations (tables or figures), then, in addition to the HTML file, the corresponding graphic files are included in the implementation of the essay. The implementation is stored, e.g., on the writer’s server. The reader accesses the server and views the essay online or downloads all files of the essay to his or her computer and reads the essay offline.

Based on [3], the process of creating an extendable essay is technically represented as follows. Initially, the text of the essay is formatted in XML; to define the hierarchical structure of the essay, a set of XML tags is defined. Then, a special program converts the text into the HTML format by inserting the fragments that make the essay interactive.

Using the technology described, three extendable essays were created: “Complexity of algorithms” [4], “Implementation of an extendable essay” [5], and “Portrait of Adele Bloch-Bauer I” [6]. The authors were faced with the problem of typing mathematical formulas, because the XML format does not provide any means for working with formulas. It is also technically difficult to include images in the essay. Finally, there are problems with typing the essay as an XML file.

When working on a text, the writer generally makes corrections, changes words, reformulates phrases, and rearranges parts of the text. When working on an extendable essay, this process becomes more complex, because the XML representation of text differs significantly from its representation on paper or in a text processor due to the large number of tags. Finding a right place in the text is quite difficult; moreover, making any changes to the text may damage its XML structure.

Thus, it would be useful for potential writers to have an editor that would allow them to work with an extendable essay without being distracted by its technical implementation. Below we discuss the Extendable Essay Editor (3E) for creating extendable essays and consider an example of an extendable essay on the Sage computer algebra system, which was created using this editor.

FUNCTIONALITY OF 3E

The editor is intended for writers of extendable essays and should enable their convenient work throughout the entire period of writing.

First of all, it is necessary to hide all technical details of essay implementation, thus allowing the writer to focus on the content of the essay itself.

The editor must provide convenient (traditional) text input and formatting.

The editor must include tools for inserting formulas and illustrations (drawings, tables, and graphs) into essays. It is important to integrate illustrative materials into the HTML file of the essay. It is more convenient for the reader to work with a single essay file than to check the integrity of the folder containing essay files.

Writing an extendable essay is a lengthy process. The editor must allow the writer to save the current version of the essay, so the writer could continue working on the essay from its last saved state.

The representation of the essay to the writer should differ from its representation to the reader (already because the writer needs to see all extensions at the same time). Hence, the editor should allow the writer to work with the essay in two modes: editing mode (to type text, add extensions, etc.) and reading mode (to check the coherence of the text when opening the extensions).

The extendable essay is provided to the reader as an HTML file; therefore, the editor must generate and export the HTML representation of the essay.

IMPLEMENTATION OF THE EXTENDABLE ESSAY EDITOR

Since extendable essays are viewed via a web browser, it seems reasonable to implement the editor as a web application. This approach has its pros and cons. Placing the editor designed as a web application on a server allows it to be accessed from any computer connected to the Internet; there is no need to install the editor on the user’s machine. The writer does not need to have any special skills to simply open the editor’s page in the browser. On the other hand, without Internet connection, the editor becomes unavailable.

Taking into account all advantages of web technologies, it was decided to develop 3E as a web application in JavaScript. As the main library, we used React, which enables efficient processing and display of dynamic web pages [7]. React is a popular open-source library that allows one to quickly and easily create high-performance web applications.

An extendable essay is represented as a JavaScript object with the following structure (see Fig. 1): at the top level, there are fields title and author. The content of the essay itself is represented as an array of parts. Each part is a JavaScript object with the following fields: partTitle is the title of a part, paragraphs is the array of paragraphs, and tasks are test questions. Each paragraph is also represented by an object with the following structure: basic is the basic text of a paragraph in the HTML format and extension is the extension of the paragraph. If there is no extension for a paragraph, then the extension field has a null value; otherwise, extension is a JavaScript object with attributes type (type of the extension) and paragraphs (array of paragraphs of the extension).

The tasks field is an array of JavaScript objects, each of which contains the text of a question (field question), an array of answers to the question (answers) with an indication of the correct answer (rightAnswer), and an explanation for the correct answer (option).

Since the internal representation of the essay uses JavaScript objects, as the storage format (external representation) of the essay, we use JavaScript Object Notation (JSON), which is a popular text-based format for transmitting data in web applications.

The editor consists of several components. The Options component (the editor’s toolbar) allows one to format the input text and save/load the JSON file of the essay. The ViewEssay component displays the essay in the reading mode. The EssayEditor component is the main component (the editor itself) responsible for displaying the toolbar and the essay in the editing mode, which enables typing, adding, and deleting paragraphs, adding and deleting extensions of all types, including test questions, as well as adding and deleting essay sections.

To represent mathematical formulas, the KaTeX library is used. The work with formulas is implemented as follows. In the editing mode, formulas are typed in the TeX format, which is familiar to the authors who write scientific texts that contain formulas, because publishers often accept papers in this format. When viewing the essay in the reading mode, the KaTeX library translates formulas on the fly into the MathML format, which allows web browsers to display formulas in a readable form.

USER INTERFACE

When designing the 3E interface, we adhered to the principles set out in [8]. The light palette was used to reduce visual stress.

When launching 3E, the window shown in Fig. 2 appears.

At the top of the editor, there is a toolbar with control buttons. Below are the fields for the title of the essay and its author (authors), as well as the fields for the text of the essay.

The toolbar buttons are grouped based on their functions: font style, text alignment, and file commands.

Group of File Commands

The editor allows the writer to save the current state of the essay on his or her computer, open the essay to continue working on it, and convert the essay to the HTML format (see Fig. 3).

Fig. 3. [Images not available. See PDF.]

Block diagram of the Extendable Essay object in the editor.

The Save and Open buttons have traditional meaning. The representation of the essay to the writer slightly differs from its representation to the reader, which is why the editor allows the writer to preview the essay. When clicking on the View button, the browser opens a new tab that shows how the essay will look like for the reader (see Fig. 4).

Fig. 4. [Images not available. See PDF.]

Home page of 3E.

At the same time, the essay has its own functionality: the reader can open and close extensions, answer test questions, etc.

The Save HTML button is used to generate the HTML file containing the essay; this file can be downloaded to the writer’s machine for subsequent transfer to the readers.

Typing and Editing the Essay Text

When launching the editor, a section (more specifically, a section title field and a field for the text of the first paragraph) is automatically created. Having finished typing the text of the section, the writer can add a new one by clicking the Add Section button (located under the body text of the section) or create test questions by clicking the Add Questions button. The editor allows the writer to delete sections; in this case, the entire section, including all its paragraphs and tests, is deleted without any notifications. To avoid mistakes, the Delete Section button differs from the buttons for deleting paragraphs in its style and is located on the right side (rather than on the left side) of the screen, more specifically, to the right of the section title.

When creating a section, a field for the first paragraph is automatically created. When filling up the first line of the paragraph, the next word is moved to the next line and the typing field is vertically expanded. When working with the text of a paragraph, the writer can select, insert, and delete text fragments by using standard keyboard shortcuts. Selected fragments can be formatted using the buttons on the left side of the toolbar at the top of the screen (see Fig. 5).

Fig. 5. [Images not available. See PDF.]

File command buttons.

To the left of the typing field, there are buttons “+”, Trash, and “”, which allow the writer to create an extension for the current paragraph, delete the paragraph (along with the extension), and add a new paragraph, respectively.

Fig. 6. [Images not available. See PDF.]

Extendable essay in the reading mode.

Images

The Img button allows the user to insert images into the essay. It is most convenient to place an image in a separate paragraph. The image can be placed at the center of the page or aligned to its right-hand or left-hand edge. Images can also be pasted from the clipboard by pressing Ctrl+V.

Fig. 7. [Images not available. See PDF.]

Font buttons.

Formulas

Mathematical formulas (e.g., ) are typed in the TeX format and enclosed in $: $\sin^2(x)$. The mathematical representation of a formula can be viewed in the reading mode.

The Extendable Essay Editor and its documentation are available at http://www.ccas.ru/ca/essay. The editor runs in any modern browser.

ESSAY “SAGE COMPUTER ALGEBRA SYSTEM: A BRIEF INTRODUCTION”

Content of the Essay

Using 3E, an extendable essay on the Sage computer algebra system was created. When writing the essay, we used the books by W. Stein [9], P. Zimmermann et al. [10], and A. Zobnin et al. [11], as well as the Sage documentation from the official website [12]. The essay describes basic Sage tools and explains how to work with polynomials and matrices.

The essay is intended for the readers who are not familiar with computer algebra systems. The Sage system is a convenient environment for gaining first experience in the field of computer algebra. There are web interfaces for working with Sage, so there is no need to download and install the system to try it out and get a first impression.

The Sage system (the exact name is SageMath) is a free open-source computer algebra system that covers various branches of mathematics. Hundreds of programmers and scientists from different countries take part in its development; the project is led by William Stein.

One of the ideas behind Sage is to take full advantage of existing math packages, instead of coding all algorithms from scratch. Sage integrates more than a hundred specialized and universal packages (e.g., GAP, PARI/GP, Singular, and Maxima), which gives it its functional power. As the system language, Python was selected. The use of this universal programming language supported by a large number of libraries is another concept behind Sage. Python also has great expressive capabilities. The essay describes constructions that form a consistent (in our opinion) subset sufficient to begin mastering Sage.

The user works with the Sage system in a dialog mode: the user enters a command and the system returns the result of its execution. A command is an order, e.g., evaluate an expression, construct a matrix, or plot a function. Sage can work with numeric and symbolic expressions; the essay describes the corresponding operations with some examples.

The section devoted to polynomials describes operations on polynomials (multiplication, exponentiation, calculation of the greatest common divisor for two polynomials, etc.) The last section of the essay is devoted to matrices (their description, basic operations on them, and solving matrix equations).

The essay “The Sage Computer Algebra System: A Brief Introduction” is available at http://www.ccas.ru/ca/essay.

Using 3E

To write the essay, 3E was run in Microsoft Edge (v. 115.0.1901.200, 64-bit, official build) and Firefox (v. 116.0.2, 64-bit) under Windows 10 and Ubuntu 22.04.3 LTS, respectively.

In addition to creating the essay itself, we also checked the performance of 3E, in particular, when working with images, formulas, extensions, etc. In addition to text, the essay also includes images. Each image is implemented as an individual paragraph and can therefore be positioned on the page using the paragraph formatting commands. The essay uses fonts of two types: serif for regular text and monospace for program code. The formulas are typed in the TeX format and enclosed in $…$; in the reading mode, the formulas are displayed in the conventional mathematical notation. The maximum depth of the extensions was set to one.

Difficulties arose when inserting special characters not available on the keyboard (e.g., those added using the Insert Symbol menu in Word). We copied these characters from other text editors.

Overall, 3E proved its effectiveness. For its further improvement, we intend to improve the interaction between the editor and the KaTeX library (up to replacing it with the translation of formulas into the MathML format), implement a function for insertion of symbols as in Word, and fix some code bugs.

ACKNOWLEDGMENTS

The authors express their gratitude to A.A. Ryabenko and D.E. Khmel’nov for numerous fruitful discussions of this work. We also thank the reviewer for useful remarks. Our special gratitude goes to S.A. Abramov, the author of the idea of extendable essays, without whom the work on the Extendable Essay Editor (3E) and the essay “The Sage Computer Algebra System: A Brief Introduction” would be impossible.

FUNDING

This work was supported by the Vladimir Potanin Scholarship Program.

CONFLICT OF INTEREST

The authors declare that they have no conflicts of interest.

Translated by Yu. Kornienko

Publisher’s Note.

Pleiades Publishing remains neutral with regard to jurisdictional claims in published maps and institutional affiliations.

REFERENCES

1 Voiskunskii, A.E.; Solodov, M.Yu. Influence of electronic text properties on reading efficiency and effectiveness: A literature review. Psikhologiya Chel. Obraz.; 2020; 2, pp. 134-142. [DOI: https://dx.doi.org/10.33910/2686-9527-2020-2-2-134-142]

2 Miall, D.S. and Dobson, T., Reading hypertext and the experience of literature, J. Digital Inf., 2001, vol. 2, no. 1. https://journals.tdl.org/jodi/index.php/jodi/article/view/35/37. Accessed July 17, 2023.

3 Abramov, S.A.; Bordachenkova, E.A.; Khmel’nov, D.E. Extendable essay as a hypertext scheme for information and educational material. Comput. Math. Math. Phys.; 2013; 53, pp. 369-374. [DOI: https://dx.doi.org/10.1134/S0965542513030020]

4 Abramov, S.A., Extendable essay “Complexity of algorithms.” http://www.ccas.ru/sabramov/essay. Accessed July 28, 2023.

5 Khmelэnov, D.E., Extendable essay “Implementation of an extendable essay.” http://www.ccas.ru/ca/_media/essayonessay_html.rar. Accessed July 28, 2023.

6 Zubareva, V.N., Extendable essay “Portrait of Adele Bloch-Bauer I.” http://www.ccas.ru/ca/_media/portrait.rar. Accessed July 28, 2023.

7 Banks, A.; Porcello, E. Learning React: Functional Web Development With React and Redux; 2017;

8 Johnson, J. Designing with the Mind in Mind: Simple Guide to Understanding User Interface Design Rules; 2010; Amsterdam, Elsevier:

9 Stein, W., Sage for power users, 2012. https://wstein.org/books/sagebook/sagebook.pdf. Accessed August 4, 2023.

10 Zimmermann, P., Casamayou, A., Cohen, N., Connan, G., Dumont, T., Fousse, L., Maltey, F., Meulien, M., Mezzarobba, M., Pernet, C., Thiéry, N., Bray, E., Cremona, J., Forets, M., Ghitza, A., and Thomas, H., Computational mathematics with SageMath, Society for Industrial and Applied Mathematics, 2018. https://www.sagemath.org/sagebook/english.html. Accessed August 4, 2023.

11 Golubkov, A.Yu., Zobnin, A.I., and Sokolova, O.V., Komp’yuternaya algebra v sisteme Sage (Computer Algebra in the Sage System), Moscow: MGTU N. E. Baumana, 2013.

12 SageMath feature tour. https://www.sagemath.org/tour.html. Accessed August 4, 2023.