Iffing

Limited facility for producing variable output.

Global Requirement

Tag the page. This takes the form:

|tag:3dec|

(or |tag:pfc| or |tag:flac3d| or |tag:common|) at the top of the page. At the bottom of the page, a corresponding definition for the substition is required:

.. |tag:3dec| raw:: html

   <div id="pagecodeid" class="hide">3DEC</div>

The |tag:3dec| must match the top, and the string inside the <div> must be either “FLAC3D”, “3DEC”, “PFC”, or “common” (all case sensitive).

All iffy behavior comes from icgscripts.js by identifying a codeofinterest in one of the following ways.

• A code name used in the tag substitution + substitution definition will set the specified code as the codeofinterest.

• When “common” is set in the tag substitution + substitution definition, the codeofinterest is determined by icgscripts.js from the doc set build (it gets the code name that appears in the page footer). (Pages should be tagged “common” if they are common/shared/single pages.)

icgscripts.js explicitly looks for a page element with the ID pagecodeid and will only do something if that ID is found.

There are now three iffy things you can do once a page is tagged and codeofinterest is determined.

Vary the Codename

Use |codename| instead of specific name substitutions (|pfc|, |griddle| etc.).

This inserts <span class="codename codeis">the program</span> wherever used.

When the page is tagged as described above, icgscripts.js finds <span> elements with class name = codeis and swaps in codeofinterest for “the program”.

Code Name Classes

The second and third iffy behaviors are built around the classnames “flac3d”, “3dec” and “pfc”, all of which have the “display” element in the style sheet set to “hide”. In other words, anything that is classed with a code name will be hidden by default.

Code-Specific Blocks

Use the following to produce a block that holds matter specific to one code, e.g.:

.. container:: 3dec

The value is case insensitive; “3dec”, “flac3d”, and “pfc” are the only valid entries in this context (do not use “common”). Remember all content of the container must be indented to the container directive level.

This creates a <div> element classed with the supplied code name.

Place additional container blocks for other codes adjacent to one another.

On a tagged page, icgscripts.js will turn on display for all found <div> elements that have a class that matches codeofinterest.

Code-Specific Inline Text

Use the roles :pfc:, :3dec:, and :flac3d: to mark inline text specific to a code. Place units for different codes adjacent to each other. This creates span elements in output that are classed to the code name indicated in the role (i.e., <span class='pfc'>some text here</span>. icgscripts.js turns on display of the text whose role name matches the codeofinterest.

Note this only works on inline units of plain text. If there is any formatted content within the role block, such as this:

:flac3d:`usually the |flac3d| command :cmd:`model.new` can be used`

errors will result, and likely poor output formatting as well. If an inline unit requires iffyness but must contain formatted content, utilize substitution.

• in the “outer” document, define substitutions for raw html for starting spans as needed and one “endspan” (can be used commonly against all “start” spans)

• insert substitutions in shared unit as needed

See Working with FISH for an example of how this is done.

Case Sensitivity &etc.

For the tag definition
(<div id="pagecodeid" class="hide">common</div> et al.)

Code names must be upper case (FLAC3D, PFC, 3DEC); “common” must be lower case.

For code blocks
(.. container:: FLAC3D et al.)

Class (the part following ::) is case insensitive. “PFC” or “pfc” are ok. “common” is nonsensical, unsupported, and should not be used.

For roles
(:flac3d:ˋsome textˋ et al.)

Always lowercase. Only :flac3d:, 3dec, or pfc are built into the system. If other codes are needed, adapt per below.

Esoterica for Inline Formatting

The technique for inline variable content will not handle anything other than plain text formatting. If something needs styling, it will be necessary to define a custom role that is classed as needed to obtain the desired formatting. So, on a page where such is needed, you’d see at the top:

.. role:: specialpfc
   :class: pfc cmdname

In this example, we want to refer in text to the PFC prompt, which should look like this: pfc>. The technique is needed since the prompt typeface is not the normal body text typeface.

The prompt is created by using the custom role: :specialpfc:ˋpfc>ˋ.

In this usage, the :class: argument for the custom role must containt the code identifier, plus the class needed to supply required formatting (“cmdname” here).

And superesoteric

• css class names cannot start with a number

• the .. container:: directive produces a <div> element that will have a class = `` whatever follows the ``:: of the directive.

This should make you afraid of this: .. container:: 3DEC. However, sphinx sets all class names to lower case no matter what, and always strips digits from the front of class names it has been given. So you’re going to get <div class="dec"> from the above. And in the meantime, even though you specified <div id="pagecodeid" class="hide">3DEC</div> as your tag, in icgscripts.js, by the time the search for matching class names occurs, the script will be looking for “dec” and not “3DEC”. No newline at end of file