Terrarum/assets/mods/basegame/books/btex.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE btexdoc SYSTEM "btexdoc.dtd">
<btexdoc cover="hardcover" inner="standard" papersize="standard">
<cover>
    <title>The Way to Mastery of<br/>Lorem Ipsum</title>
    <subtitle>Or, How To Write and Publish a Book</subtitle>
    <author>Terran Publishing</author>
    <edition>Test Edition</edition>
</cover>

<tocpage><tableofcontents/></tocpage>

<manuscript>
    <part>The Book</part>

    <chapter>What Is a Book</chapter>

    <p>This example book is written to give readers the example of the Book Language.</p>

    <section hide="1">What Qualifies as a Book</section>

    <p><index id="the book"/>Under the book typesetting system, a Book is a collection of texts typesetted for an improved
        legibility, enumerable pages, with insertion of other helpful resources such as illustrations
        and <a href="hyperlink">hyperlinks</a>.</p>
    <p>Books are considered as bound and always presented in two pages for reading.</p>

    <chapter>Writing a Book Using a Typewriter</chapter>

    <p><index id="typewriter"/>Typewriter allows quick scribbling of the words in convenient manners, just click on them and get
        writing!</p>
    <p>But it comes with big downsides: you cannot type in multiple writing systems, cannot have defined
        chapters and sections, cannot include any illustrations, no hyperlinks, and of course, ragged texts.</p>
    <p>Typed papers are considered as non-bound and only one page at a time will be presented.</p>
    <p>All in all, you cannot write a true Book using a typewriter.</p>

    <chapter>Writing a Book with Publishers and Printing Presses</chapter>

    <p>Professional-looking texts, with all the benefits of a real Book can be made, or even mass-produced
        easily with the help of publishers.</p>
    <p>To have your precious texts to be printed, you must send your manuscripts to a publisher, and the
        manuscript must be written in a special language: the <btex/>.</p>
    <p><btex/> allows concise description of the entire shape of your book, any style the book typesetting
        system can support can be described and printing presses will produce the papers accordingly.
        You can even try to mimic the look and feel of papers created using a typewriter, if you want to.</p>


    <part>The <btex/></part>

    <chapter>Introduction</chapter>

    <p><index id="btex language"/><btex/> (pronounced as /biːtɛk/) is a markup language based on XML, with a resemblance of the <latex/>.
        <btex/> abstracts away the meticulous styling and typesetting configurations, so you can focus on
        actually writing your texts than debugging the <latex/> macros. This does come with a downside of
        not being able to change the given style.</p>
    <p><btex/> document is divided up to five parts: the <a href="btexdoc">Style Declaration</a>, the
        <a href="cover">Cover</a>, the <a href="table of contents">Table of Contents</a>, the
        <a href="manuscript">Manuscript</a>, and the <a href="index page">Index Page</a>, of which the
        Style Declaration and the Manuscript are the mandatory parts.</p>


    <chapter>The Style Declaration</chapter>

    <p><index id="btexdoc"/>The Style Declaration is the very first line of a <btex/> document. Its syntax is as follows:</p>

    <callout align="left" class="code"><index id="btexdoc (tag)"/><!--
    -->&lt;?xml version="1.0" encoding="UTF-8"?&gt;<br/><!--
    -->&lt;!DOCTYPE btexdoc SYSTEM "btexdoc.dtd"&gt;<br/><!--
    -->&lt;btexdoc cover="hardcover" inner="standard" papersize="standard"&gt;
    </callout>

    <p>The <code>btexdoc</code> tag takes following attributes:</p>
    <ul>
        <li><code>cover</code> — changes the style of the cover. Possible values: <code>hardcover</code>, <code>none</code></li>
        <li><code>inner</code> — changes the style of the body. Possible values: <code>standard</code>, <code>typewriter</code></li>
        <li><code>papersize</code> — defines the size of the paper. Possible values: <code>standard</code></li>
    </ul>

    <chapter>The Cover</chapter>

    <p><index id="cover"/>The Cover defines the text on the cover of the book. If your text has no cover, this part can be omitted. Its syntax is as follows:</p>
    <callout align="left" class="code"><index id="cover (tag)"/><index id="title (tag)"/><index id="subtitle (tag)"/><index id="author (tag)"/><index id="edition (tag)"/>&lt;cover hue="358"&gt;<br/><!--
-->　　&lt;title&gt;Title of your book&zwsp;&lt;/title&gt;<br/><!--
-->　　&lt;subtitle&gt;Subtitle if necessary&zwsp;&lt;/subtitle&gt;<br/><!--
-->　　&lt;author&gt;Who wrote this book&zwsp;&lt;/author&gt;<br/><!--
-->　　&lt;edition&gt;Edition information if necessary&zwsp;&lt;/edition&gt;<br/>
&lt;/cover&gt;
    </callout>
    <p>Only the <code>title</code> tag is mandatory. Cover texts will be printed using a special font that has wider
        gaps between characters. The title text will be printed in a double-size.</p>
    <p>The cover can have different colour with the <code>hue</code> attribute, which takes a number between 0 and 360.</p>

    <chapter>The Table of Contents</chapter>

    <p><index id="table of contents"/>The contents of the Table of Contents is filled in automatically by reading through your manuscript;
        parts, chapters and sections will be added. Its syntax is as follows:</p>

    <callout align="left" class="code"><index id="tocpage (tag)"/>&lt;tocpage title="Custom page name if necessary"&gt;&zwsp;&lt;tableofcontents/&gt;&zwsp;&lt;/tocpage&gt;
    </callout>

    <p>The optional <code>title</code> attribute allows a custom name can be given to this page.
        If unspecified, the default name is “Table of Contents”.</p>
    <p>The tag <code>&lt;tableofcontents/&gt;</code> is an internal tag used by the typesetter.</p>


    <chapter>The Manuscript</chapter>

    <p><index id="manuscript"/><index id="tags"/>This is the part where you actually write your body texts in. The body text can have the following tags:</p>
    <ul>
        <li><index id="part (tag)"/><code>part</code> — inserts part separation page to your book</li>
        <li><index id="chapter (tag)"/><index id="section (tag)"/><code>chapter</code>, <code>section</code> — inserts a new chapter/section. If an alternative name is required on the Table of Contents, the <code>alt</code> attribute can be used. If the chapter/section needs to be hidden on the Table of Contents, add the <code>hide="1"</code> attribute. If the chapter must start on a new page, see <a href="macro definition">the Macro Definition</a></li>
        <li><index id="p (tag)"/><code>p</code> — inserts a new paragraph. The body texts must be written inside this tag. All paragraphs will have a 16-pixel indentation, with the following exceptions: first <code>p</code> of the part/chapter/section; first <code>p</code> after <code>br</code>, <code>newpage</code>, <code>callout</code>, <code>ul</code>, <code>ol</code> or <code>anonbreak</code></li>
        <li><index id="span (tag)"/><code>span</code> — allows changing the colour or the style of the texts. The colour must be specified in the <code>colour</code> attribute. Six-digit hex code, three-digit hex code and CSS Colours Level 4 named colours are supported. Note that all the colours will be rounded to the nearest three-digit hex code</li>
        <li><index id="emph (tag)"/><code>emph</code> — is a special case of the <code>span</code> tag. The resulting text will be <emph>red</emph></li>
        <li><index id="itemname (tag)"/><code>itemname</code> — is a special case of the <code>span</code> tag used to highlight the name of the ingame item. The resulting text will be <itemname>blue</itemname></li>
        <li><index id="targetname (tag)"/><code>targetname</code> — is a special case of the <code>span</code> tag used to highlight the name of an arbitrary target or goals. The resulting text will be <targetname>green</targetname></li>
        <li><index id="code (tag)"/><code>code</code> — is a special case of the <code>span</code> tag used to highlight the code element in-line. The resulting text will be <code>magenta and monospaced</code></li>
        <li><index id="br (tag)"/><code>br</code> — self-closing tag; inserts an anonymous line break</li>
        <li><index id="newpage (tag)"/><code>newpage</code> — self-closing tag; inserts an anonymous page break</li>
        <li><index id="anonbreak (tag)"/><code>anonbreak</code> — self-closing tag; inserts a paragraph break in the text. The break will be in a form of a long straight line on the centre of the text. Useful for typesetting novels</li>
        <li><index id="callout (tag)"/><code>callout</code> — is a paragraph box that holds a text in a grey box</li>
        <li><index id="ul (tag)"/><index id="li (tag)"/><code>ul</code> — starts an unordered list. List elements are defined using the <code>li</code> tag</li>
        <li><index id="ol (tag)"/><code>ol</code> — starts an ordered list. List elements are defined using the <code>li</code> tag</li>
        <li><index id="fullpagebox (tag)"/><code>fullpagebox</code> — is used to typeset its child tags into a box that fills an entire page, with its contents centred on the page. Must be used after the <code>newpage</code></li>
        <li><index id="btex (tag)"/><code>btex</code> — self-closing tag; inserts an inline form of the <btex/> logo in the text</li>
    </ul>
    <p>Self-closing tags have no child tags. To use a self-closing tag, simply do <code>&lt;tagname/&gt;</code>.</p>


    <section>Heading Styling</section>

    <p>The <code>part</code>, <code>chapter</code> and <code>section</code> takes optional <code>type</code> attributes which changes how the chapter should be numbered. Available options are:</p>
    <ul>
        <li><code>a</code> — use alphabets for the number (a, b, c, …)</li>
        <li><code>A</code> — use majuscule alphabets for the number (A, B, C, …)</li>
        <li><code>i</code> — use Roman numerals for the number (i, ii, iii, …)</li>
        <li><code>I</code> — use majuscule Roman numerals for the number (I, II, III, …)</li>
        <li><code>1</code> — use Arabic numerals (1, 2, 3)</li>
    </ul>
    <p>By default, parts use majuscule Roman numerals and others use Arabic. Alternative styling for the <code>part</code> and the <code>chapter</code> can be defined using <a href="macro definition">the Macro Definition</a>.</p>


    <section>Paragraph Styling</section>

    <p>The <code>p</code> and <code>callout</code> tags can take <code>align</code> attribute, which controls how the text should be aligned. Available options are:</p>
    <ul>
        <li><code>left</code> — aligns the text flush to the left without breaking words, also known as ragged-right</li>
        <li><code>right</code> — aligns the text flush to the right without breaking words, also known as ragged-left</li>
        <li><code>center</code> — aligns the text aligned at the centre along the width of the paper without breaking words</li>
        <li><code>justify</code> — aligns the text as evenly as possible, similar to real books. This is the default value.</li>
    </ul>
    <p>The <code>p</code>, <code>span</code> and <code>callout</code> tags also take <code>class="code"</code> attribute, which results in the text printed using the <span class="code">code font.</span></p>


    <section>Hyperlinking</section>

    <p><index id="hyperlink"/>Hyperlinks can be defined using <code>index</code> and <code>a</code> tags.</p>
    <ul>
        <li><index id="index (tag)"/><code>index</code> — will define a target for a link. Indices require a unique identifier to work as a link, and the identifier must be defined in the <code>id</code> attribute</li>
        <li><index id="a (tag)"/><code>a</code> — will make its child texts to be clickable. The link target (index identifier) must be defined in the <code>href</code> attribute</li>
    </ul>


    <section>Figures</section>

    <p><index id="img (tag)"/>Figures, or external images can be inserted using the self-closing <code>img</code> tag.
        This tag inserts the image at the centre of the page, starting from the current line;
        if the size is taller than the remaining lines, the image will be printed onto the next page.
        Its syntax is as follows:</p>

    <callout align="left" class="code"><!--
    -->&lt;img src="http(s) or file URL" height="8"/&gt;<br/><!--
    -->&lt;img fromgame="basegame:gui/small.png" height="4"/&gt;
    </callout>

    <p>The <code>height</code> attribute specifies the height of the image <emph>in the number of lines</emph>,
        rather than pixels, the width is calculated automatically; image width wider than the text width
        will cause an error. The tag optionally takes caption attribute which prints a text below the image.</p>

    <p>Supported image formats: JPEG, PNG, BMP or TGA</p>


    <chapter>The Index Page</chapter>

    <p><index id="index page"/>The contents of the Index Page is filled in automatically by reading through your manuscript.
        All the usage of <code>index</code> tags will be shown here. Its syntax is as follows:</p>

    <callout align="left" class="code"><index id="indexpage (tag)"/>&lt;indexpage title="Custom page name if necessary"&gt;&zwsp;&lt;tableofindices/&gt;&zwsp;&lt;/indexpage&gt;
    </callout>

    <p>The optional <code>title</code> attribute allows a custom name can be given to this page. If unspecified,
        the default name is “Index”.</p>
    <p>The tag <code>&lt;tableofindices/&gt;</code> is an internal tag used by the typesetter.</p>


    <chapter>Ending the Document</chapter>

    <p>The <btex/> document must begin with the opening <code>btexdoc</code> tag, and therefore must
        end with a matching closing tag. Simply write away <code>&lt;/btexdoc&gt;</code> and the
        document is finished.</p>


    <chapter>Conclusion</chapter>

    <p>The finished book description using <btex/> can be sent to a publisher, and if there are no errors
        on your submission, the printed books of specified number of copies will be delivered to your
        location within a reasonable amount of business days. Happy writing!</p>



    <part>Advanced Macros</part>


    <chapter>The Macro Definition</chapter>

    <p><index id="macro definition"/>This part explains the set of macros the typesetting system uses,
        and how you can manipulate them to introduce a limited set of customisations.</p>
    <p><index id="macrodef (tag)"/>Macros can be defined using the <code>macrodef</code> tag which comes before the
        <code>cover</code> tag. Its syntax is as follows:</p>

    <callout align="left" class="code">&lt;macrodef&gt;<br/><!--
-->　　&lt;pair key="macro name" value="the value"/&gt;<br/><!--
-->　　&lt;pair key="another macro" value="its value"/&gt;<br/><!--
-->&lt;/macrodef&gt;</callout>


    <section>Macro Keys</section>

    <p>Internally, part and chapter headings are printed using macros. Changing the value of the macro
        will change how the heading numbers are printed. The following is a list of names and default values:</p>

    <ul>
        <li><index id="thepart (macro)"/><code>thepart</code> — Part heading. Default: <code>Part %1$s</code></li>
        <li><index id="parttype (macro)"/><code>parttype</code> — Default style of the <code>part</code> tag. Default: <code>I</code></li>
        <li><index id="thechapter (macro)"/><code>thechapter</code> — Chapter heading. Default: <code>%1$s</code></li>
        <li><index id="chaptertype (macro)"/><code>chaptertype</code> — Default style of the <code>chapter</code> tag. Default: <code>1</code></li>
        <li><index id="chapteronnewpage (macro)"/><code>chapteronnewpage</code> — Controls if a chapter must start on a new page. Put non-zero value to enable this behaviour. Default: <code>0</code></li>
        <li><index id="resetchapterafterpart (macro)"/><code>resetchapterafterpart</code> — Controls if the chapter number should reset after a part. Put non-zero value to enable this behaviour. Default: <code>0</code></li>
        <li><index id="parindent (macro)"/><code>parindent</code> — Controls the indentation size of the paragraphs. Default: <code>16</code></li>
    </ul>

    <p>The argument key <code>%1$s</code> will be replaced into a number, Roman numerals, etc.
        depending on the value of <code>type</code> attribute.</p>

    <p>These macros can be used to localise the chapter headings into your language. For example,
        in Korean text, the following idiomatic definition will be desirable:</p>

    <callout align="left" class="code">&lt;macrodef&gt;<br/><!--
-->　　&lt;pair key="thepart" value="제%1$s부"/&gt;<br/><!--
-->　　&lt;pair key="parttype" value="1"/&gt;<br/><!--
-->　　&lt;pair key="thechapter" value="%1$s장"/&gt;<br/><!--
-->&lt;/macrodef&gt;</callout>


    <chapter>Printing External Variables</chapter>

    <p><index id="v (tag)"/>Defining the text to be printed outside the typesetting system, such as the name of the sender
    and the recipient, can be desired. These texts can be used with the self-closing <code>v</code> tag. This tag
        can also be used to use an ingame string as well.</p>
    <p>To print an external variable, use the <code>id</code> attribute; to print an ingame string, use
    <code>fromgame</code> attribute. Note that only one of two attributes must be used, using both
        attributes in a single tag will cause an error.</p>

    <section>Printing the Ingame Currency</section>

    <p><index id="bucks (tag)"/>In order to print a text such as “The total is <bucks>1234</bucks>”, the <code>bucks</code>
        tag can be used along with the <code>v</code> tag. The following code is an example case:</p>

    <callout align="left" class="code">&lt;p&gt;The total is &lt;bucks&gt;&lt;v id="invoice_total_amount"/&gt;&lt;/bucks&gt;&lt;/p&gt;</callout>

    <p>If the external variable <code>invoice_total_amount</code> contains a string <code>toomany</code>,
        this code would print out “The total is <bucks>toomany</bucks>”.</p>


    <section>Korean Language Specific Tags</section>

    <p><index id="korean postpositions"/>To accommodate the Korean Postposition transformations, special <code>v</code> series tags are added:</p>

    <ul>
        <li><index id="veun (tag)"/><index id="vneun (tag)"/><code>veun</code> <code>vneun</code> — 은/는</li>
        <li><index id="vi (tag)"/><index id="vga (tag)"/><code>vi</code> <code>vga</code> — 이/가</li>
        <li><index id="veul (tag)"/><index id="vreul (tag)"/><code>veul</code> <code>vreul</code> — 을/를</li>
        <li><index id="vwa (tag)"/><index id="vgwa (tag)"/><code>vwa</code> <code>vgwa</code> — 와/과</li>
        <li><index id="vro (tag)"/><index id="veuro (tag)"/><code>vro</code> <code>veuro</code> — 로/으로</li>
    </ul>

    <p>Either of the tag in the pair can be used; they will put the correct postposition based on the word.
        In other words, <code>veun</code> and <code>vneun</code> are identical.</p>
    <p>These tags can be used in the following situation: suppose you have a <btex/> document,</p>

    <callout align="left" class="code">[en] Send your &lt;v fromgame="GAME_ITEM_HOLOTAPE"/&gt; that contains the manuscript to the publisher via mail to have your books printed.<br/><!--
    -->[koKR] 원고가 담긴 &lt;veul fromgame="GAME_ITEM_HOLOTAPE"/&gt; 출판사로 우편을 통해 보내야 책이 인쇄됩니다.</callout>

    <p>The variables will be resolved based on the current ingame language, then the necessary
        linguistic processing is performed, which would result in a following paragraph
        (text in blue denotes the text is inserted using the tags):</p>

    <callout>[en] Send your <itemname>Holotape</itemname> that contains the manuscript to the publisher via mail to have your books printed.<br/><!--
    -->[koKR] 원고가 담긴 <itemname>홀로테이프를</itemname> 출판사로 우편을 통해 보내야 책이 인쇄됩니다.</callout>



    <part>Non-laymen Zone</part>

    <chapter alt="The Waiting Process">Why Wait for the Books to be Printed? Why Can’t I just Print Them by Myself?</chapter>

    <p>The <btex/> engine is not fast; it takes at least a few seconds to print a book. The “waiting”
        system is there because the book is being printed in the background on separate threads
        (yes, they are multi-threaded!) to not interfere with the normal gameplay, or else the players will
        encounter the freezing every time the book is being printed, and this would be a huge minus towards
        the gameplay experience.</p>

    <p>If the process exits without any error, the mailing system will be
        notified and will send the mail containing finished books to the player; if the process exits
        with errors, the mail containing details of the errors will be sent instead.</p>

    <p>For this reason, the “printing press” is not exposed to the player, they only get to interact with it
        indirectly through the “publisher” via mail.</p>




    <newpage/>

    <fullpagebox>
        <p><span colour="#666">this page is intentionally left blank</span></p>
    </fullpagebox>

</manuscript>

<indexpage><tableofindices/></indexpage>
</btexdoc>