search

HFOSSedu / GitKit-Text

The source for the GitKit Textbook
MIT License
0 stars 7 forks source link

readme

The GitKit Text

This repository contains the pretext source for the GitKit Runestone texts.

If you are interested in using the GitKit Text please see the Instructor Guide in the text on Runestone by using one of the following links:

Licensing

Licensing information for the GitKit activities can be found in the LICENSE.md file.

Contributing

  1. Fork the upstream repo.
  2. Open your fork in a Codespace using the green "Code" button.
  3. Edit and commit changes to a feature branch.
  4. Push and make a Pull Request

PreTeXt References

These are some helpful PreTeXt references:

Overall Repository Structure

The files and folders in source include:

Terminology

Use standard preTeXt terminology when refering to elements in the text. For example:

Authoring Section Files

Typcial File Structure

The code below shows the skeleton of a prototypcial section:

<?xml version="1.0" encoding="UTF-8"?>

<section
  xml:id="topic-section-title"
  xmlns:xi="http://www.w3.org/2001/XInclude"
  >
  <title>Section Title</title>
  <introduction>
    ...
  </introduction>
  <exercises>
    <title />
    ...
    <exercise
      xml:id="ex-some-exercise"
      label="ex-some-exercise">
    </exercise>
    ...
  </exercises>
  <conclusion>
    ...
  </conclusion>
</section>

Including a Subsection

If a section contains subsections then each <subsection> gets its own <exercises> division as follows:

<?xml version="1.0" encoding="UTF-8"?>

<section
  xml:id="topic-section-title"
  xmlns:xi="http://www.w3.org/2001/XInclude"
  >
  <title>Section Title</title>
  <introduction>
    ...
  </introduction>
  <subsection>
    <title>Subsection Title</title>
    <introduction>
      ...
    </introduction>
    <exercises>
      <title />
      ...
      <exercise
        xml:id="ex-some-exercise"
        label="ex-some-exercise">
      </exercise>
      ...
    </exercises>
    <conclusion>
    ...
    </conclusion>
  </subsection>
  <conclusion>
    ...
  </conclusion>
</section>

Notes:

xml:ids and labels

xml:ids and labels are attributes assigned divisions/elements that help to identify them. Both xml:ids and labels are required to be unique across the entire text.

A division/element in the preTeXt document will have an xml:id attribute if:

Every <exercise> and <task> will have both an xml:id and a label attribute with the same value.

Naming Conventions

To help ensure that xml:id and label values are unique across the entire text and are also discoverable they will follow a set of rules:

Some examples follow:

<section 
  xml:id="topic-section-title">
  ...
</section>

<figure 
  xml:id="fig-figure-description">
  ...
</figure>

<exercises>
  <exercise 
    xml:id="ex-exercise-description" 
    label="ex-exercise-description>
    <task 
      xml:id="ex-task-description" 
      label="ex-task-description>
      ...
    </task>
    ...
  </exercise>
</exercises>

Other Cases

Creating Links

Any division/element with an xml:id can then be linked to by using an xref as follows:

<xref ref="ex-foss-community-principles-q1"/>

Tip for Discovering Existing xml:ids for xrefs

Use grep to find existing labels to link to. For example:

$ grep -R 'xml:id' .        # All
$ grep -R 'xml:id="fig-' .  # Figures

Section Content

Text Styling

Use text styling consistently throughout the document as follows:

Escaping Characters

The < symbol is the start of a tag and must be escaped as &lt; when used in preText. For consistency and readability is it generally a good idea to escape both < and >. For example:

git branch &lt;branchName&gt;

which will render as:

git branch <name>

Similarly the & character can be escaped as &amp;.

Adding Images

Each chapter folder has an images folder to contain the images used in that chapter. In addition, there is a shared-images directory in the source folder that can be used for any images that appear in multiple chapters.

If a new chapter is added:

Images contained in one of the chapter's images folder can be placed in the text by using the chapter name in the source. For example:

  <image source="images/ch-community-collaboration/basic-foss-workflow.png" width="75%">
    <description>The main project repo is forked into your GitHub space to create your remote copy.  Your remote copy is then cloned into your local development environment to create your local copy. Changes to your local copy are pushed to your remote copy and a pull request is made to the main project.
    </description>
  </image>

Adding Exercises

The following subsections give general guidelines for adding <exercise>s.

General Rules

Multiple Choice
Multipart Questions

An <exercise> containing <task>s can be used to create a question with multiple parts. For example:

<exercise
  xml:id="ex-sample-with-tasks"
  label="ex-sample-with-tasks">
  <introduction>
    <p>Text introducing the set of questions.</p>
  </introduction>
  <task
    xml:id="ex-sample-with-tasks-a"
    label="ex-sample-with-tasks-a">
    ... task content ...
  </task>
  <task
    xml:id="ex-sample-with-tasks-b"
    label="ex-sample-with-tasks-b">
    ... task content ...
  </task>
</exercise>

Note:

Adding Version Specific Content

There are 10 versions of the text that can be built:

Building a Specific Version

Any of these versions can be built using "Build another target..." option on the PreTeXt menu or by using terminal commands similar to:

pretext build instructor-web-linux
pretext view instructor-web-linux
Adding KitClient Specific Content

Content specific to a given kit client is indicated by adding a component attribute to to divisions/elements as follows:

  <p 
    component="linux-kit-client"
    xml:id="topic-some-stuff-linux">
    This text appears only in the Linux Kit Client versions.
  </p>

  <p 
    component="vscode-kit-client"
    xml:id="topic-some-stuff-vscode">
    This text appears only in the VSCode Kit Client versions.
  </p>
Instructor Version Content

A commentary element with the component="instructor" attrribute is used to add instructor guide information directly to the source text as follows:

 <commentary component="instructor">
    <tabular top="major" bottom="major" left="major" right="major">
      <col width="100%" />
      <row>
        <cell>
          <p>
            <alert>Instructor Note:</alert>: Information for the instructor appears here.
          </p>
        </cell>
      </row>
    </tabular>
  </commentary>

Note:

Defining a Version

The available versions are defined by the <target>s in the project.ptx file. Each <target> references a .ptx file in the publication folder that indicates the content that will appear in the version.

Publishing a Version

Runestone does not currently support the publication of different versions of a text from a single repository. Instead, the solution is to create a fork of this repository. Then in that repository change the publication file that is the target of the runestone target to point to the publication file for the version that you would like to publish. Then create a new Runestone text using that repository.

See the GitKit-VSCode Repository for an example. That repository also includes information about how to update it from this repository when edits are made.