User Stories

[oscarlevin]

Please contribute User Stories here

[hammadmazhar1]

As a new user to PreTeXt, I want to write my journal article in PreTeXt, so that I can put up a web version of my article on my website and have it converted to whichever journal style I submit it to easily.

I am familiar with command-line interfaces, so I setup PreTeXt based on the guide, using the PreTeXt CLI route on my local machine. I ask the CLI to create a new article project for me.

I look through the directory structure, determine what parts of my article go where, use PreTeXt tags and attributes as I should.

After I complete my authoring, I identify the LaTeX style file (.sty) that my journal of choice uses, and place it in my PreTeXt directory as indicated. I edit my PreTeXt publication file to point to the needed style, and hit/type the build commands.

After compilation, I have my web version which looks pretty and nice and organized, and I have a document ready for journal submission for peer review.

[stephen-flood]

Use case: new user, single existing document in latex.

I am a mathematician who authors a lot of documents in latex. I see the nice websites for pretextbooks, and I would like to compile my existing documents into these websites.

I use windows, so I go to the PreTeXt project page and I download a single windows .exe file that installs PreTeXt into my system (like Miktex), never mentioning anything about Python or CLI, or anything else.

I open the packaged PreTeXt document editor (like the latex editor that comes with Miktex), and open my LaTeX file. The viewer happily displays my code in LaTeX, perhaps underlining portions that will work less well with PreTeXt.

I hit Compile, and the source compiles directly from LaTeX to web. I make some edits in the latex again, and hit compile again, and it works seamlessly.

[anuragkatyal]

This does sound mighty nice...

[sean-fitzpatrick]

I'm coordinating intro calculus, and in charge of preparing weekly worksheets for tutorials. At the beginning of the semester, I type pretext new worksheets (note the plural), and I get a directory containing a sample worksheet, and a file that contains common information (course number, semester, etc.).

I fill out the file with the necessary information, and then edit the sample worksheet to create my first tutorial worksheet.

Later in the semester, while in that directory, I type pretext new worksheet, and a new sample worksheet is created that includes the information in the common info file. I author the exercises for that week, build the worksheet to PDF, and head off to the photocopier.

[stephen-flood]

Use case: new user, entire course of documents already written in LaTeX.

Same as above, but instead of asking the PreTeXt document editor to open a single document, I tell it to open a Folder. It automatically recognizes the documents, and any \include and \input relationships between them. It also automatically identifies the appropriate type of PreTeXt document type, and separately compiles the LaTeX files into pretext, and then outputs.

Finally, it packages all those outputs together into a single webpage (as with the book landing page earlier today).

[davidaustinm]

It's the middle of a semester in which I'm teaching linear algebra. I have everything for the course available in a new-ish type of pretext project, and I just want to add a new worksheet into it without creating a new project. Then the existing publication file will be applied to any new documents in the project so that the writing experience and the visual appearance of everything is consistent.

Last time I taught the course, I had a great activity for the topic that's coming next, and I would like to reuse it with some light edits. Unfortunately, the existing activity is in latex, but don't worry! I just type
pretext new worksheet next_activity.tex
and next_activity.ptx appears in the source directory of my existing course repository. If I'm lazy, i could just compile a worksheet (in html or pdf) from this file without doing anything else. If I want a PDF, then all the spacing from the latex document will be preserved. But last time the students had some small issues with one part of the activity so I can easily edit the .ptx file to add some more scaffolding and whatnot and then compile.

[mattboelkins]

I'm teaching a class and I want to write a single-class lab or small-group activity for my students. Imagine calculus or linear algebra as a topic setting.

I want to be able to have a standalone document that I can open in an easy-to-use editor, start typing directions and questions for my students, and include some interactives. For example, I might want to include a Doenet interactive in a calculus activity, or a Sage cell in a linear algebra activity.

I would want to be able to share the HTML output of the document with my students so that they can use the interactives within the document itelf, say using movable graphics in Doenet or executing various commands in Sage. I'd also want there to be a print/PDF version of the document so that students can handwrite responses to the prompts (either on paper or on an iPad).

***** I think the above is a sufficient user story; what I write below is additional wishful thinking *****

I wonder about the possibility or desirability of having output/work from students in the document that could be saved, submitted, and possibly even marked by the instructor. For sure it would be nice if students could have an easy-to-organize library of saved work on activities/labs such as these.

[agreicius]

The course builder

• Create a course project using pretext new course.
• The project has four subprojects: textbook, class meetings, syllabus, worksheets, exams.

Textbook

The textbook project is structured as a PreTeXt book project. As course progresses sections (or chapters) are added to the textbook. These sections include: official statements of definitions, theory, algorithms; examples that may or may not be covered during a given class meeting; computational cells; some exposition.

Worksheets

The worksheets subproject allows me to make stand alone work sheets, which are gathered in a separate collected worksheets object.

Exams

Similarly, in the exams subproject I can make individual exams, which can be gathered in a course exams object. (On a higher level, my course has a collected exams object associated to it that has all exams of all iterations of the course gathered.

Class meetings

Not totally sure what this means, actually. Supposed to decouple the material covered in a class meeting from the textbook. Perhaps a given class meeting entry pulls a relevant worksheet, and pulls the relevant defs, thms, etc. from the textbook (without the exposition).

Coordination

• The various course objects I've created can be shared with colleagues intending on teaching the course in a similar manner.
• If navigate to the relevant department-wide shared folder, source files of previous iterations of course can be imported to various subprojects using pretext blah.

[sean-fitzpatrick]

I'm preparing a midterm for a large class, where students like to peek at what their neighbour is doing. I use the CLI to create a new exam, and begin filling it out. There is a file containing the basic information for the exam, so I only need to worry about writing the questions.

Within each <question>, I am able to include multiple <variation>s (<version> is already taken...)

I write 5 questions, with 4 variations each, giving me 1024 unique versions of my exam.

Using the CLI, I run pretext build exam --copies=400, 400 versions of my exam are created as PDF files, and it's time to head to the printer again.

[oscarlevin]

Tom Cruise has been assigned to teach the section of Discrete Mathematics using DMOI, which starts in a week. Having never taught it before, he starts by creating a new PreTeXt course by navigating to his Teaching folder and typing pretext new course --name math228f2043. He receives a message that the course has been created. He then opens the newly created math228f2024 folder in VS Code and sees an uncluttered list of files, including

• A courseConfig.ptx file
• A syllabus.ptx file
• A calendar.ptx file
• A main.ptx file
• Folders labeled Activities, Exams, Homework, Notes, each containing a file titled sample-[typename].ptx.

Since he wants to start by writing his syllabus, he opens the syllabus.ptx file and sees an XML structure that has has entries for all the standard syllabus elements. He fills in these elements, and adds a few more. When he starts typing a new tag for "student hours" it auto-completes this for him so he can just enter the times.

He thinks it looks good, so, instead of hitting the "preview" button (he is Tom Cruise after all) he types pretext build syllabus and a preview in the right side of the editor pops up showing him what the syllabus looks like.

He then types pretext build course and gets shown a preview of the entire course, with links to the syllabus, calendar, activities, and notes.

He realizes that his course is only going to contain lecture so he won't have any activities. He opens the CourseConfig.ptx file and sees that he can set <course-elements><activities include="no"/></course-elements>. He rebuilds and sees the course site looking much better.

Then he tries to create the notes for the first day. He types pretext new notes. A new file inside the notes folder is created and opened, prompting him to save it with a file name. He chooses day1notes.ptx. The file has some xml tags already so he can start typing notes. When he types pretext build, this file is built since it was the most recent one that was saved. He likes what he sees, so he hits print and a sheet with the notes is sent to the printer. He then runs pretext deploy and sees the entire course site, with notes, updated on the web.

Then he defuses the bomb and heads to class.

[hammadmazhar1]

I wonder if you can provide some sort of a 'config' file that lays out the course structure (and type) that you would have and generate based on that.

[anuragkatyal]

This story assumes a pretext book that includes activities, worksheets, and homework problems already exists.

To create an on-demand standards-based assessment, I'd like to be able to pull parametrized questions from relevant sections and have a printed version available within 20-30 seconds. The workflow involves me clicking on the questions, modifying them quickly, if needed, and viewing the simultaneous output on the right side of the screen. I could reorganize the questions by picking them up and moving them around. I could drag the bottom of the box around each question to adjust the amount of space after each question. Before printing the assessment, I'd have the option to print a class set or print it for a select group of students. Each assessment would print with a QR code and a box underneath for a score on the assessment, so scanning the QR code would upload the student's grade to a spreadsheet somewhere or the LMS directly. Perhaps there is a box next to each question, and scanning the QR code adds the points in all the individual boxes and uploads the total.

[Tanaquil18]

I want to create an exam, to be printed and taken on paper. I have an old exam to start from, or a current exam for a different section of the course. I make a copy of it. I want to easily reorder the choices of any multiple choice questions or no-work-needed questions, as well as shuffle the order of the questions themselves sometimes. I want to be able to update the graphs and formulas to new versions. I want space automatically added between questions, but for things to fit nicely on the pages. I want the points to add up to 100. I want to be able to print and email to the testing center or print services.

More ideally, I'd like a pool of questions and be able to swap them out, with tags on questions so that I can select topics or objectives or features each question tests/uses, such as graphical limit, definition of derivative with a quadratic, etc. If this comes from the textbook instead of from things I've written, even better!

[davidfarmer]

Jeeves taught linear algebra in the Fall and is teaching it again in the Spring.

He makes a copy of the course folder on his laptop, goes into it, and edits the copy of the
baseinfo.txt file. He modifies the academic term line, changing "Fall" to "Spring" and
adding one to the "Year".

Most of the other lines in the file, providing his name, office number, institution identifier,
etc, do not need to change. He thinks about changing the office hours line, taking away
the hour on Friday and adding a 3rd hour on Tuesday, but eventually decides not to make
the change.

After closing the file, he rebuilds the course. This automatically generates a syllabus and
dynamic calendar, which have the correct days and days of the week because the academic
calendar for his institution was automatically derived from the information in the baseinfo file.

Jeeves was glad it was so easy, because previously he had to do a bunch of work to manually
edit the baseinfo file before building the course: change more lines to the correct starting date
of the semester, Spring break dates, etc.

[davidfarmer]

Bertie is teaching a new course, so he needs to make a syllabus.

Since he had previously created a syllabus, he already has a myinfo file which knows
his name, office number, email address, etc. That information is automatically imported,
which saves him a few minutes of typing.

[Tanaquil18]

I want to be able to give term start date and end dates, planned breaks, how many tests, how many class meetings per week and on which days, and then have a calendar or list of meeting dates where the material for each day, things due before class, during class, after class appear (possibly because I've already done it for a previous semester, possibly because the textbook author has provided the suggested scheduled).

I want to designate some things that stay on Mondays always (metacognition journals). I want most things to be able to move but in a sensible way - homework and tests after the material is covered in class, etc. I want a warning if keeping the metacognition journal fixed changes its position relative to tests in certain ways (test used to be on Wednesday, but this semester is Friday).

[stephen-flood]

I'm a user who has created a couple of single file "one-off" worksheets, which have in-file publication options set (as a header or footer). I now want to package them together into a course package.

I run "pretext one-off create-course wksh1.ptx wksht2.ptx ... wksht40.ptx"

That pulls out the publication options from each of the files, merges them into a single ptx file, and warns me if their options are incompatible.