Learning by doing - 5e Reference manuals in XML

[Myrdin Potter]

Goal - make a reference manual using Notepad++ in XML.

https://media.wizards.com/2017/dnd/downloads/SA-Compendium.pdf

Desired document in reference manual format to share with players during games in easy readable format.

Step one, take the master XML document and pare it down to just the reference manual. Master template can be found here:

https://www.fantasygrounds.com/forums/showthread.php?36157-5e-Asset-Templates

I attached what I think I need to start with to this post. Does it look right?

[Zacchaeus]

Yes, looks like you've got all the bits

[Myrdin Potter]

Ok, time to try cutting and pasting into the XML. From the notes, it looks like I cut and paste a page at a time from the source.

Source has really big heading font, regular heading font, horizontal lines, bold text and a few shaded text sections. Will have to look all of that up too.

[Nickademus]

One problem you may run into is that there is only one header font in the formatted text blocks.

[Myrdin Potter]

It is only the grand title at the very top of the PDF that is the extra big header font. Can live with that.

Need to decide what chapters are so what shows up at the left for organization. The original document is just one long PDF of rules clarifications.

[Nickademus]

Yep. And remember, you can always grab the Unearthed Arcana module to look through a completed reference manual.

[Myrdin Potter]

The problem with that is that if I do, I will be completely overwhelmed as you have so much in it.

I do not even know haw to use N++. I don't know where lf vs. cr lf comes from, how I do one or the other or why it matters.

I do not know how to comment out or uncomment in the XML.

I am not 100% certain which words are just a foo and I need to replace them and which are system required and touching them will cause California to sink into the sea.

So I need to take things in small pieces and learn each step.

Please be patient with me.

[Myrdin Potter]

My first question.

<xxPage>

According to your top level comment, XX means swap out.

Do I swap out with anything:

page001

or just the xx:

001Page

?

[Myrdin Potter]

To be more clear, let me say this is the entire reference manual content I want:

Sage Advice Compendium
The Sage Advice Compendium collects questions and answers
about the rules of Dungeons & Dragons (fifth edition).
These are the official rulings of Jeremy Crawford, the
game’s lead rules developer.

First, all the text needs to be tagged with the right formatting.

<h> and </h> are for header test, so I need to tag like this:

<h>Sage Advice Compendium</h>
<p>The <i>Sage Advice Compendium</i> collects questions and answers
about the rules of <b>Dungeons & Dragons</b> (fifth edition).
These are the official rulings of Jeremy Crawford, the
game’s lead rules developer.</p>

Then what?

I want two column text throughout the reference manual. I see:

<xxBlockName2>
<blocktype type="string">text</blocktype>
<align type="string">left,right</align>
<text type="formattedtext"><p>xxText</p></text>
<text2 type="formattedtext"><p>xxText</p></text2>
</xxBlockName2>

But what relationship does that have with:

<xxPage>
<name type="string">xxPageName</name>
<!-- #This text can be used as the only text of the page or as text preceding the list
of blocks -->
<text type="formattedtext">xxText</text>

Where does the formatted text go?

[Nickademus]

My first question.

<xxPage>

According to your top level comment, XX means swap out.

Do I swap out with anything:

page001

or just the xx:

001Page

?
The 'xxPage' can be anything you want so long as it follows these xml rules:

1. It must be unique among the pages (no two pages should have the same name).
2. It cannot contain spaces.
3. It must start with a letter or underscore.
4. It can only contain letters, numbers, underscores, and periods.

The default that FG uses when it makes xml elements is 'id-00001', 'id-00002', etc., but these aren't very descriptive.


To be more clear, let me say this is the entire reference manual content I want:

Sage Advice Compendium
The Sage Advice Compendium collects questions and answers
about the rules of Dungeons & Dragons (fifth edition).
These are the official rulings of Jeremy Crawford, the
game’s lead rules developer.

First, all the text needs to be tagged with the right formatting.

<h> and </h> are for header test, so I need to tag like this:

<h>Sage Advice Compendium</h>
<p>The <i>Sage Advice Compendium</i> collects questions and answers
about the rules of <b>Dungeons & Dragons</b> (fifth edition).
These are the official rulings of Jeremy Crawford, the
game’s lead rules developer.</p>

Then what?

I want two column text throughout the reference manual. I see:

<xxBlockName2>
<blocktype type="string">text</blocktype>
<align type="string">left,right</align>
<text type="formattedtext"><p>xxText</p></text>
<text2 type="formattedtext"><p>xxText</p></text2>
</xxBlockName2>

But what relationship does that have with:

<xxPage>
<name type="string">xxPageName</name>
<!-- #This text can be used as the only text of the page or as text preceding the list
of blocks -->
<text type="formattedtext">xxText</text>

Where does the formatted text go?

A page is the entire right side of the reference manual. It is made up of a series of blocks. You would use a different block each time you want to have a different format. For just two columns of text each page, you will only need one block in the page (the block containing the green text in your quote). Something that may be confusing you is that each page can also have some formatted text at the top. This text (shown as blue text in your quote) can only be one column and can't display any images. It more of a quick, simple text section for when you don't need anything fancy. You won't want to use this.

You would want the page to look like this:


<xxPage>
<name type="string">xxPageName</name>
<xxBlockName2>
<blocktype type="string">text</blocktype>
<align type="string">left,right</align>
<text type="formattedtext">
<h>Sage Advice Compendium</h>
<p>The <i>Sage Advice Compendium</i> collects questions and answers about the rules of <b>Dungeons & Dragons</b> (fifth edition). These are the official rulings of Jeremy Crawford, the
game’s lead rules developer.</p>
</text>
<text2 type="formattedtext">
<p>(column #2 text)</p>
</text2>
</xxBlockName2>
</xxPage>

[Myrdin Potter]

xxBlockName2 has the "xx". Do I need a new block name per page or something?

[Nickademus]

Each block name within a page must be unique (otherwise the last will overwrite a previous).

[Myrdin Potter]

Since each page is different, I can keep reusing the same block name over and over as long as not repeat in one page?

And for two columns, there is no autowrap, I need to decide myself what text in each column?

[Nickademus]

Since each page is different, I can keep reusing the same block name over and over as long as not repeat in one page?Yes.


And for two columns, there is no autowrap, I need to decide myself what text in each column?

Not sure what you mean by autowrap, but each column exists in one of the two halves of the page. The block will continue down the page until the longest column has displayed all of its text.

[Myrdin Potter]

So I need to balance the text myself.

Will do a full page tomorrow and hopefully name the .mod properly and see if it displays.

If that works, then will look at the other two code blocks. Not sure what I am supposed to do with the chapters block.

[Myrdin Potter]

Well some progress.

I learned every <h> means you need to close <p> and then reopen it.

What is the story with " and '? Or at least the curly versions in PDFs?

What the first page looks like ...(in attached file which is about all I can show as too much will cause copyright issues)

[Zacchaeus]

Well some progress.

I learned every <h> means you need to close <p> and then reopen it.

What is the story with " and '? Or at least the curly versions in PDFs?

Fantasy Grounds can't handle some kinds of quotation marks. You'll need to change them to more standard ones.

[Nickademus]

Well some progress.

I learned every <h> means you need to close <p> and then reopen it.

<h> is for a header; <p> is for a paragraph. They are mutually exclusive. So is <table>, <list>, and <frame>.

[Myrdin Potter]

And CR and LF in the text do not add them, you need the <p> and </p>.

How do you generally generate the text that goes into your XML? Hand coding all the <p> and such will drive me insane.

[Trenloe]

See "Internal Representation" for what markup you can use: https://www.fantasygrounds.com/refdoc/formattedtextcontrol.xcp

Either hand code it, or do it within a story entry in a FG campaign and copy the XML created in the campaign db.xml file.

[Myrdin Potter]

I already have that link open, but thanks.

So make story entry, look in campaign db.xml, cut and paste, rise and repeat?

Does N++ have a way of autochecking that all tags are closed?

[Trenloe]

Does N++ have a way of autochecking that all tags are closed?
If you install the "XML Tools" plugin it does. you'll see some options under Plugins -> XML Tools.

[Nickademus]

And CR and LF in the text do not add them, you need the <p> and </p>.

How do you generally generate the text that goes into your XML? Hand coding all the <p> and such will drive me insane.

I create templates that have all the xml code. Then I just copy/paste the raw data from the source to a placeholder. (You have already seen this in my module.) I rarely have to type <p> anymore.

[Myrdin Potter]

I create templates that have all the xml code. Then I just copy/paste the raw data from the source to a placeholder. (You have already seen this in my module.) I rarely have to type <p> anymore.

Not sure how that works.

Your template has the space to put the text in, but a long block of text in a column will have a bunch of paragraphs but all be in the same column. So how do you avoid <p></p> pairs?

Also, how to you deal with &? D&D has the & and the second D blue. If I remember right from some fuzzy mark-up in LaTeX or something & is used as an escape character to say replace with this ASCI character instead. Or something like that. What if you want a &?

[Myrdin Potter]

See "Internal Representation" for what markup you can use: https://www.fantasygrounds.com/refdoc/formattedtextcontrol.xcp

Either hand code it, or do it within a story entry in a FG campaign and copy the XML created in the campaign db.xml file.

What is the format to do an indented list with dots?

How does <p>, <list> and <li> all interact?

[Zacchaeus]

Enclose paragraphs with the <p></p> tags.

You'll need to replace '&' with '&amp; so D&D becomes D&amp;D

[Trenloe]

What is the format to do an indented list with dots?

How does <p>, <list> and <li> all interact?
It's a limited form of HTML. Find some online tutorials that cover those. <list> is an unordered list - so HTML will use <ul> instead of FGs <list>.

Or, just do some basic formatting through the FG interface in a Story entry and look at the resulting markup in the campaign db.xml file. Just give it a try and see what markup FG creates.

[Nickademus]

Not sure how that works.

Your template has the space to put the text in, but a long block of text in a column will have a bunch of paragraphs but all be in the same column. So how do you avoid <p></p> pairs?

Also, how to you deal with &? D&D has the & and the second D blue. If I remember right from some fuzzy mark-up in LaTeX or something & is used as an escape character to say replace with this ASCI character instead. Or something like that. What if you want a &?

For multiple paragraphs of text, I usually have a '<p>xxx</p>' or '<p>xxDescription</p>' in the <text> section of the xml. I click the line and hit Ctrl+D a number of times equal to the paragraphs there are. (I can't remember if this is the default hotkey for Duplicate Line or if I changed it to that.) Then I select the first 'xxx' and copy/paste the first paragraph, select the second 'xxx' and copy/paste the second paragraph, etc. I can usually move a text only article of Unearthed Arcana over to the xml in 5-15 minutes depending on the number of pages.

Something else you may not have run into yet: FG doesn't have an em dash. It just uses a hyphen. So if you find the author of the content you are converting likes to heavily use em dashes (like Mike Mearls), you are better off changing them all to double hyphens so they have the length in FG to have the same visual effect.

[Myrdin Potter]

I figured out the list format.

<list></list> replaces <p></p> and then you have each list item enclosed with <li> and </li>.

Fixed the emdash, fixed the &.

No really sure what Nickademus is suggesting for the <p></p> as it seems to be - count the number of paragraphs, make that many pairs of tags, paste each paragraph into a pair.

Next up - figure out chapters and sub-chapters. Like what relationship do pages have to each.

And what does that XXPageName at the top that is a link mean and what happens in multiple pages.

[Nickademus]

The xxPageName is the name of the link that appears at the top of the right side of the reference manual. It is often overlooked as just a title, but it is a link that will open the reference manual page in window separate from the reference manual.

As for the chapters and subchapters, just look at existing reference manuals and see how the section tree in the left side works. You click on a chapter name and it opens to display all the subchapters. You click on a subchapter name and it opens to display all the pages. You click on a page name and the page is displayed to the right.

[Myrdin Potter]

This is way, horribly slow for me, but I do have 2 pages entered. Not really sure I understand the XML, but getting some of the data entry down.

How do I make a block of text shaded compared to the others? The text above and below in the column are the standard no shade, but one paragraph is shaded?

How do I make a horizontal rule line across the column (same color as heading text)?

[Myrdin Potter]

In block1, the simple text block, the comments have the following options:

<!-- Possible frame styles: 'blue', 'brown', 'green', 'pink', 'picture', 'page',
'sidebar', 'text 1', 'text2', 'text3', 'text4', 'text5' -->
<frame type="string">xxFrame</frame>

What exactly are these options? I looked quickly in the wiki and did not see the page with them described.
Does this apply to the 2 column format or just the simple text block?

The document I am using as my first conversion has shaded sections of text to indicate what was new since the last update (background color). Is that possible in a 2 column text block?

Do you need to use a series of 2 column text blocks to stack on top of each other if you want to mix in other types like different background colours?

[Trenloe]

In block1, the simple text block, the comments have the following options:

<!-- Possible frame styles: 'blue', 'brown', 'green', 'pink', 'picture', 'page',
'sidebar', 'text 1', 'text2', 'text3', 'text4', 'text5' -->
<frame type="string">xxFrame</frame>

What exactly are these options? I looked quickly in the wiki and did not see the page with them described.
These are the frame names that identify which FG frame to use for that block of text. Look in the ruleset graphics\frames directory, these should be PNG graphics files in the format refblock_<frame name>.png


Does this apply to the 2 column format or just the simple text block?
The Wiki (https://www.fantasygrounds.com/wiki/index.php/Reference_Manuals) mentions that frames can be used in text blocks. It doesn't distinguish one or two columns. It should work in both. My recommendation is to give it a try.

[Myrdin Potter]

I am unclear on exactly what I am supposed to do when a paragraph in a column is supposed to be shaded. Most of the column is standard but one paragraph is an update so the original document has it shaded.

For the examples, you want me to look into the file folders on my computer for the assets used? Not on the wiki?

[Trenloe]

I am unclear on exactly what I am supposed to do when a paragraph in a column is supposed to be shaded. Most of the column is standard but one paragraph is an update so the original document has it shaded.
If you want to change the format of any text within a page then you need to put it in a new block. See the options within the <blocks> -> <[block_01]> set of data in the "Reference Manual Pages" section here: https://www.fantasygrounds.com/wiki/index.php/Reference_Manuals All of the various options are assigned to a block. Use extra blocks if you need to have different text formatting.


For the examples, you want me to look into the file folders on my computer for the assets used? Not on the wiki?
As I mentioned above, the actual frame graphics are in the ruleset, not in the wiki. All the wiki does is list a name. So if you want to know what "text4" looks like, for example, then look in the ruleset graphics files. These frames could change from ruleset to ruleset as developers create different frames with a ruleset/theme specific feel. I suggest you look at the ruleset frame files I mentioned above in post #33.

[Myrdin Potter]

I copied the 5e .pak file to a different folder, made it a .zip and then opened it up.

There is a file called "graphics_frames.xml" and a folder with .png graphic files in it.

If I look through the .xml, I don't see the same names as the examples in the reference manual Wiki.

As for shading a paragraph, I understand that you can keep stacking blocks in a page until you close the block tag. For a 2 column text block, can you shade the left column and not the right or the right column and not the left?

As it is, you need to eyeball the placement and manually balance and then put into the XML. I only see options for blocks, not pieces of a block.

[Trenloe]

I copied the 5e .pak file to a different folder, made it a .zip and then opened it up.

There is a file called "graphics_frames.xml" and a folder with .png graphic files in it.

If I look through the .xml, I don't see the same names as the examples in the reference manual Wiki.
As mentioned in the Wiki: "Frames are defined by the ruleset. Any frame defined whose name starts with "referenceblock-" can be used. The ones listed here are included with CoreRPG ruleset."

Always remember to look in any layered rulesets being used!

[Trenloe]

As for shading a paragraph, I understand that you can keep stacking blocks in a page until you close the block tag. For a 2 column text block, can you shade the left column and not the right or the right column and not the left?
In two column blocks a <frame> will only be applied to the right hand text.

[Myrdin Potter]

So if the shading was in the left column in the original, you are out of luck then?

[Nickademus]

Yep. Just swap them for the reference manual.

[Myrdin Potter]

I can't swap them without rewriting the piece to begin with. And if I were doing that, why not just use a simple text block.

I guess I will have to use ** ruling ** instead.