This file describes how to modify the QuickStart documentation.
An overview -- each documentation page as a file foo-source.html. When
you run build.bat, it runs BuildQuickStart.exe on *-source.html, which does a
couple things:
- Creates foo-frames.html and foo-noframes.html versions of the source
page.
- Inserts samples wherever it sees %% filename.xaml%% in the source HTML.
Be inserted html will include the xaml, the JavaScript (if applicable), and
a "preview" jolt ActiveX control.
- For the frames version, creates a table of contents panel on the left
(basically, inserts NavigationPanel.html)
- Find any hyperlink pointing to *-source.html and replace it with *-frames.html
or *-noframes.html as appropriate.
When you create a sample, put it in the samples directory and create a sample
that can be run by itself. Remember that any functions and global
variables you define in JavaScript should have unique names because when
deployed to the quick start, your sample will be running alongside other
samples.
Where to get the source for the quick starts: everything lives in the source
depot provided by http://toolbox. To enlist:
- md directory
- cd directory
- set sdport=BGIT-SDTOOLBOX:4001
- c:\nt\tools\x86\sd.exe client
and set the view to:
//depot/JoltQuickStartTools/... //MYMACHINENAME/...
- Look in the QuickStart subdirectory
BuildQuickStart.exe supports the following %% constructs:
- %% filename.xaml%% -- inserts samples\filename.Xaml and
samples\filename.js, along with a preview. If the JavaScript file is
empty, BuildQuickStart.exe won't display the script.
samples\filename.html should also exist so you can run your sample alone,
but BuiltQuickStart.exe pays no attention to it.
- %% filename.xaml showpreview=false %% -- starts with the sample's
preview hidden
- %%filename.xaml C#=mydir\myclass.cs%% -- displays C# code. The
JavaScript file is still assumed to exist. You'll need to manually
copy the sample's dll into the QuickStart directory.
Make sure to put directives on their own line, in a paragraph by themselves,
e.g.:
<p> %% filename.xaml%% </p>
In theory, all %% directives are case-insensitive and ignore whitespace, but
this hasn't been heavily tested.
Xaml, JavaScript, and C #files also support their own directives to control
which text should be bold. Put the directive on its own line inside a
comment (using the appropriate comment format for the source file), whitespace
is not supposed to be significant. Supported directives:
//emphasize sometext --
bolds the next occurrence of "sometext". You can declare several
emphasized directives before any of the text to be emphasized occurs (which
is useful in XML, where you can't put comments inside elements)
<!--begin emphasis--> --
starting here, all lines will be bold until the end emphasis directed is
hit. These directives do not nest.
<!--end emphasis-->
<!-- begin collapsed-->
-- starting here, all lines will be hidden (not rendered) until the
corresponding end collapsed directive. These directives do not nest.
<!--end collapsed-->
Interesting files:
- *-source.html -- are run through BuildQuickStart.exe. Make sure
</body> is on a line by itself, as BuildQuickStart.exe inserts some things
right before this tag.
- *-frames.html -- generated by BuildQuickStart.exe
- *-noframes.html -- generated by BuildQuickStart.exe
- NavigationPanel.html -- BuildQuickStart.exe inserts this file into the
-frames version of -source.html files. BuildQuickStart.exe only
inserts things inside the <body> tag, the rest is ignored. Make sure
<body> is on a line by itself.
- FrameTemplate.html -- describes how *-source.html and
NavigationPanel.html should be combined into a single file
- samples\activex_template.html -- this HTML defines what the jolt preview
will look like for a sample. BuiltQuickStart.exe will insert this HTML
into *-source.html, once per sample.
- samples\per-page-template.html -- this HTML is inserted at the end of
every *-source.html file, right before the </body> tag.
- stylesheet.css -- most of the look and feel as defined here, I tried to
write clean HTML.
- template\template.html -- used by NewJoltProject.exe
- template\template.js -- used by NewJoltProject.exe
- template\template.xaml -- used by NewJoltProject.exe
In general, these tools probably don't handle invalid xaml very well.
My HTML editor of choice is Expression Web.