Generating a Page Exploring a Source File
The source file being explored is called "packageMember" or "xxx" for short.
This file, xxx.java, must have tags on each inline as described in SXData.
The web page for xxx.java will reside in the application's base directory at
xxx-tour/
Steps to construct and upload the source explorer for xxx:
1. List the source files to be explorable in build.xml by defining
<property name="explorable.classes" value="xxx yyy ..."/>
2. Build target
init-explorables
This build creates and populates, for each member of explorable.classes,
the directories xxx-tour, xxx-tour/notes, xxx-tour/subsets, xxx-tour/images,
and one xxx-tour/subsets/SSS for each subset SSS.
3. Define any desirable properties in distsrc/Proto.properties.
These are then available as ant properties in build.xml. All
ant properties are available to be incorporated in notes files
with the (cumbersome) syntax:
<?php echo $ant['property.name']; ?>
4. Edit the following files to be specific to the project. These files
are used in later steps to create additional files (which will themselves
need to be edited).
notes/SX-xxx-emptyNote.html
notes/SX-xxx-emptySubsetNote.html
notes/SX-xxx-SUBSET.jnlp
notes/SX-xxx-NotesTemplate.php
notes/SX-xxx-NotesInfo.txt
5. Build target
prep-explorable-notes
Runs SourceExplorer with operation CREATENOTES for each xxx.
Creates a notes/featurename.html file for each feature and subset.
Each file will have as its initial contents either notes/SX-xxx-emptyNote.html
or notes/SX-xxx-emptySubsetNote.html. The target also creates xxx-SSS.jnlp in
each sub-directory SSS of xxx-tour/subsets.
6. The hard/interesting part. Edit the files generated in step 4 to describe
the features and subsets. Put images in xxx-tour/images. You can upload the
notes files to a browsr and they will appear much as they will in the final.
7. Build target
make-explorable-subsets
Each of the subset directories xxx-tour/subsets/SSS will be populated with
the files needed so a reader can download the subset with either jnlp
or an InstallxxxSSS.jar. (See the SelfInstall project.)
8. Build target
upload-explorables
Except for the notes/ directory, all files created above are uploaded to
the server. The result may be viewed at
the-project-site/xxx-tour/index.php
9. Review the generated result.
10. Make revisions. Earlier steps can be rerun without harm. I've tried
to ensure that should-be-edited files are not overwritten.
If you want a file to be regenerated, move it elsewhere and rerun the
step that created it.