source: docs/Balisage13/balisage-1-3-xsl/README.xml @ 4857

Last change on this file since 4857 was 3040, checked in by ksherdy, 6 years ago

Added .css files to output directory. Formatting updates.

File size: 7.5 KB
Line 
1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE article SYSTEM "file:/W:/Projects/Balisage/DTD/balisage-1-2.dtd">
3<?xml-stylesheet type="text/css" href="balisage-author.css" title="Authoring" alternate="no"?>
4<?xml-stylesheet type="text/xsl" href="balisage-html.xsl"?>
5<article version="5.0-subset Balisage-1.2" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
6  <title>Balisage authoring stylesheets README</title>
7  <info>
8    <abstract>
9      <para>A quick README describing the stylesheets available for authors writing Balisage papers
10        in XML, with <quote>how to</quote> instructions.</para>
11    </abstract>
12    <author><personname><firstname>Wendell</firstname><surname>Piez</surname></personname><personblurb><para>Wendell Piez has participated in Balisage since its inception in 2008, and in
13        many other XML and markup industry conferences before and since.</para></personblurb>
14      <affiliation>
15        <orgname>Mulberry Technologies, Inc.</orgname>
16      </affiliation></author></info><para>Two XSLT stylesheets are provided in this distribution for the convenience of Balisage authors
17    writing conference papers, along with related materials:</para><itemizedlist><listitem>
18      <para><code>balisage-html.xsl</code> is a <quote>plain preview</quote> stylesheet generating a
19        simple (HTML) web page suitable for printing. The CSS file <code>balisage-plain.css</code>
20        is referenced by HTML generated by this stylesheet, and should be placed alongside these
21        results.</para>
22      <para>This stylesheet may be used <quote>standalone</quote>.</para>
23    </listitem>
24    <listitem>
25      <para><code>balisage-proceedings-html.xsl</code> generates an HTML version of a paper in the
26        form it will appear in conference proceedings, with <quote>Proceedings look and
27        feel</quote>. The CSS stylesheet <code>balisage-proceedings.css</code> should be used with
28        its results.</para>
29      <para>This stylesheet calls in <code>balisage-html.xsl</code> as an imported module, so that
30        the logic used by both stylesheets is consistent. (Only the layout is different.) It will
31        not work if <code>balisage-html.xsl</code> is not also present in the same
32        subdirectory.</para>
33      <para>It will be a kindness to Balisage <emphasis role="ital">not</emphasis> to post on the
34        Internet any XML using this stylesheet or HTML generated from it. In order to avoid brand
35        confusion, please use the plain preview stylesheet instead, or a variant you create for
36        yourself.</para>
37    </listitem>
38    <listitem>
39      <para>Three graphic icons are called by the results of the Proceedings look-and-feel
40        stylesheet, and should be placed in the subdirectory where these results (or the XML source,
41        if rendering in a browser) are placed:</para>
42      <itemizedlist>
43        <listitem>
44          <para><code>minus.png</code>: <inlinemediaobject>
45              <imageobject>
46                <imagedata fileref="minus.png" format="png"/>
47              </imageobject>
48            </inlinemediaobject></para>
49        </listitem>
50        <listitem>
51          <para><code>plus.png</code>: <inlinemediaobject>
52              <imageobject>
53                <imagedata fileref="plus.png" format="png"/>
54              </imageobject>
55            </inlinemediaobject></para>
56        </listitem>
57        <listitem>
58          <para><code>eks.png</code>: <inlinemediaobject>
59              <imageobject>
60                <imagedata fileref="eks.png" format="png"/>
61              </imageobject>
62            </inlinemediaobject></para>
63        </listitem>
64      </itemizedlist>
65    </listitem>
66    <listitem>
67      <para>In addition, the CSS stylesheet <code>balisage-author.css</code> is provided, to apply
68        directly to a Balisage paper, for use (for example) in structured editors. It is standard
69        CSS and should work in a variety of tools, with minimal modification or tuning. (It has been
70        tested in oXygen 11.2).</para>
71      <para>This stylesheet calls in an additional CSS stylesheet, <code>docbook-table.css</code>,
72        to handle table formatting. Even without this module, it should degrade gracefully (although
73        of course tables will not be supported as fully).</para>
74    </listitem></itemizedlist>
75  <section>
76    <title>How to use the XSLT</title>
77    <section>
78      <title>In a browser</title>
79      <para>Web browsers now supporting XSLT 1.0 transformations include Mozilla/Firefox, MS
80        Internet Explorer, Apple Safari, Opera, and others. Browsers generally support a standard
81        binding mechanism between an XML document and a stylesheet, in this
82        form:<programlisting xml:space="preserve">&lt;?xml-stylesheet type="text/xsl" href="balisage-html.xsl"?></programlisting>Place
83        this code (referencing the stylesheet you want) at the top of your document, and open it in
84        your browser. (Note that some browsers require the stylesheet to be in the same subdirectory
85        as the document, out of security concerns.)</para>
86      <para>When using a browser to transform your XML directly, CSS stylesheet(s) and icons should
87        be in the same subdirectory as the (XML source) document, and images called by the document
88        should be positioned correctly relative to it.</para>
89    </section>
90    <section>
91      <title>In a standalone processor</title>
92      <para>The stylesheets use standard XSLT 1.0, so any conformant XSLT 1.0 processor can convert
93        XML valid to the Balisage 1.2 DTD (or to RNG or XSD variants thereof) into HTML.
94        Configuration will depend on your tool.</para>
95      <para>After running a transformation and writing (serializing) the HTML results to a file, be
96        sure that CSS stylesheets and icons needed for the display are placed in the same
97        subdirectory as the HTML file, and that any images called by the file are positioned
98        correctly relative to it.</para>
99    </section>
100  </section>
101  <section>
102    <title>How to use the CSS</title>
103    <para>To achieve formatted display in a structured XML editor such as oXygen, XMetaL or XMLMind,
104      use the <code>balisage-author.css</code> stylesheet provided here, binding it with a similar
105      processing instruction at the top of your XML
106      document:<programlisting xml:space="preserve">&lt;?xml-stylesheet type="text/css" href="balisage-author.xsl"?></programlisting></para>
107    <para>Note that depending on your authoring environment's support of CSS, you may have variable
108      results. Consult your product documentation, or compare this CSS directly with CSS known to
109      work in your tool, if you find adjustments need to be made.</para>
110  </section>
111  <section>
112    <title>Examples</title>
113    <para>This README document is an example of a valid Balisage paper with its stylesheet linked:
114      open it in a browser and see (if you haven't already). As distributed, it calls in the plain
115      preview stylesheet.</para>
116    <para>In addition, a mockup of a Balisage paper, <link xlink:type="simple" xlink:show="new"
117        xlink:actuate="onRequest">TagZoo.xml</link>, calls the Proceedings stylesheet.</para>
118    <para>In both documents, the <code>DOCTYPE</code> declaration has been commented out to
119      facilitate processing in uncontrolled environments; to validate either, correct and uncomment
120      its declaration, or include another schema binding.</para>
121  </section></article>
Note: See TracBrowser for help on using the repository browser.