1 Special Case - Slide Markup

1.1 Never in Slides

The markers {{{ and }}} can be used to surround text that will only appear in any output format except Slides.

This paragraph will appear in

* scrolls
* pages
* but not in slides.

This paragraph will appear in

• scrolls
• pages
• but not in slides.

1.2 Slides Only

Conversely, the markers [[[ and ]]] can be used to surround text that will appear only in Slides.

This paragraph will appear in

* slides
* but not in scrolls and pages

2 The General Case

2.1 Macro Conditional Commands

The macro commands that allow this are

%if macroName …%else…%endif

If macroName has been defined as a macro, then include the text after the %if and exclude the text after the %else. If macroName has not been defined as a macro, then ignore the text after the %if and include the text after the %else.

• The %else part can be omitted if it is empty.

%ifnot macroName …%else…%endif

If macroName has not been defined as a macro, then include the text after the %if and exclude the text after the %else. If macroName has been defined as a macro, then ignore the text after the %if and include the text after the %else.

• The %else part can be omitted if it is empty.

Example 1: Selecting Text

I might include the following in a course syllabus:

---

%define [summerSemester] [] [1]
⋮
%if summerSemester

The final exam is held on the last day of classes.

%else

The final exam is held during exam week, according to the
scheduled published by the Registrar's office.

%endif

---

By removing or restoring the %define line, I can quickly switch between summer and regular-semester versions of the yllabus.

Example 2: Suppressing Text

Sometimes I have old text that I don’t actually want to delete, but don’t want to appear in the current website. I can “comment out” such text like this ….

---

%if _ignore
⋮
…text that won’t appear in the website…
⋮
%endif

---

Of course, I never define a macro names “_ignore”.

2.2 Predefined Macros for Conditional Text

There are two macros that are pre-defined when processing primary documents:

1. The format (scroll, slides, pages, directory, …) in which the document is being processed is added as a macro named with a leading underscore, e.g., _slides.

   In fact, the {{{ and }}} markers introduced earlier are just macros providing a convenient shorthand for %ifnot _slides and %endif.

2. In the course configuration build.gradle, you can specify a property “delivery”, e.g.,

   course {
       courseName        = 'CS 361'
       courseTitle       = 'Advanced Data Structures and Algorithms'
       ⋮
       delivery          = 'online'
   }
   

   Whatever value is given to this property is declared as a macro, again named with a leading underscore. In this example, a macro named _online would be declared.

   This property could be any string, but I usually use either “online” or “live”.

3 Hybrid Course Documents

I teach many courses in both live and web versions.

In a typical live course, I prepare slides which contain a lot of terse bulleted lists, in which I fill in the details while speaking during the lectures. For example:

When preparing a web version of the course, I revisit those lists, and insert an approximation of what I would have said during lectures, but make this additional text conditional on not being processed in slides format.

For example, the original slide

# Integration Testing


\firstterm{Integration testing} is testing that combines
    several modules, but still falls short of exercising the entire program
    all at once. 


*  Integration testing usually combines a small number of
    modules that call upon one another.
   

*  Integration testing can be conducted 
    *  \firstterm{bottom-up}
        *   relieves the need for stubs

    *  or \firstterm{top-down} 

might become

# Integration Testing


\firstterm{Integration testing} is testing that combines
    several modules, but still falls short of exercising the entire program
    all at once. 


*  Integration testing usually combines a small number of
    modules that call upon one another.
   

*  Integration testing can be conducted 
    *  \firstterm{bottom-up }

        {({
        (start by unit-testing the modules that don't call anything
        else, then add the modules that call those starting modules
        and thest the combination, then add the modules that call
        those, and so on until you are ready to test
        <span class="function">main()</span>.)
        })}


        *   relieves the need for stubs

    *  or \firstterm{top-down} 

        {({

        (start by unit-testing <span class="function">main()</span> with stubs for
        everything it calls, then replace those stubs by the real
        code, but leaving in stubs for anything called from the
        replacement code, then replacng those stubs, and so on, until
        you have assembled and tested the entire program).

        })}

{({It's worth noting that unit testing and integration testing can
sometimes use some of the same test inputs (and maybe the same
expected outputs), because we are testing the software in different
configurations.})}

The upshot of this is that my original slides remain and can still be used for live presentations. But the scroll format will contain the more detailed text, and can be deployed as the web course content or as lecture notes for students in the live version.