Section 4.16 Data Files
In concert with interactive programs (see Section 4.15) you can define a file of data that may be employed by those programs. The necessary element is
<datafile>. It requires a @label attribute. The @filename is also required and is the name the file is known by in an ActiveCode program. Do not try to impose any sort of directory structure on this name. Just a filename. In the case of a text file (see below), the @editable attribute is optional. The value no is the default, with yes as the other option. The attributes @rows and @cols are optional for text files, and default to 20 and 60 respectively. Finally, a non-editable text file (only) may have its contents hidden by setting the @hide attribute to yes, rather than the default value of no.Where might you place a
<datafile>? Lots of places are possible, such as in an <example> or a programming <exercise>, close to an ActiveCode <program>. So, in expository material or in activities for readers to work through. The purpose-built COMPUTATION-LIKE block, <data>, which will get you a heading, number, title, cross-reference target, etc. (see List 4.2.2), is an option if the file itself needs more prominence or dedicated explanation. Notice that this feature is very powerful, and thus requires a bit of machinery to support. If you just want to point your reader to a file (and leave them to work with it outside of your project), either globally or locally, the read about the <dataurl> element at Section 4.16.Text as Data Files.
Inside of a
<datafile> place an <pre> element. There are then two options: provide the contents of the text file right in your source PreTeXt file, as you might for other preformatted text, or supply a @source attribute whose value is the name of an external text file you provide. The former is appropriate for “toy” examples, while the latter may be used for “serious” files with many lines, or with long lines. Note that if you provide the file as the content of the <pre> element, it can be indented to match your source file indentation, and will undergo some manipulation, such as removing leading whitespace, and ensuring a final newline, but preserving any relative indentation. If provided via a @source attribute, there is no manipulation.Such a text file may be declared editable by the reader, presumably to allow them to witness the resulting behavior of a some employing program. The
@rows and @cols attributes describe the viewport into the file provided in the HTML output. Typically scrollbars will allow the reader to survey all of a large file. In static outputs, the first few lines are shown, given by the value of @rows, and lines are truncated according to the value of @cols.Images as Data Files.
Inside of a
<datafile> place an <image> element with a @source attribute. As usual, this attribute should be the name of an external file you provide. Most common formats are supported, but it is important to use standard extensions, so the format can be discerned. Now this file may be explored programmatically by opening the file using the name provided in @filename.Keep the size of the image small, say 300–400 pixels in each direction. You may also supply the usual layout controls, such as
@width, and these will be consulted in the formation of output formats. Ideally, you should use a width that scales the image to look something like its “native” resolution, since part of an image-processing exercise may depend on this aspect of the input. HTML output uses a 600 pixel overall width, so a percentage can be computed based on this parameter.Notes on Data Files.
Some notes that apply to each type of data file.
- Note that the name of the data file in a
@sourceattribute need not have any resemblance to the new name given to the file via the@filenameattribute. In other words, the reader will never know (or care) what@sourcewas. - Whenever the
@sourceattribute is used, there needs to be an advance step performed by the CLI Section 5.2 or thepretext/pretextscript (Chapter 47) to generate an auxillary file (yes, a third file!) to aid the transistion from an external file to a file that can be used by the reader in programs. -
In all cases, for an HTML build the contents of the data file live within an HTML page, as text for a text file, and as a base-64 encoding for an image file. Hence for a non-Runestone build, any employing program must be on the same page, and an author should think ahead about the granularity of how a project might be chunked into pages (Section 44.1).In a build for use on Runestone Academy, the file will be in the Runestone database and usuable throughout.
-
Some
<program>run entirely in your browser, on Runestone Academy or not. An example is when@languageis set topython. Other<program>, such asjavawill only execute when hosted on Runestone Academy.In the latter case, you need to do just a bit more than try to open a data file in your program’s code. Include a@datafileattribute on the<program>element that is a list (separated by commas or space) of the filenames for files that will be used (these are the names given by the@filenameattribute of the<datafile>element).
