Reference Manual XML help

[GunbunnyFuFu]

Hey all...need another set of eyes to help me see why this reference manual isn't displaying. The reference manual entry itself shows, and when clicked opens a window that has "Reference" at the top, but the left side (Navigation) is totally blank. I've looked and looked...this is a copy/paste with some minor adjustments made (changed module name to my current module).



<chapter_700_referencemanual>
<chapters>
<chapter_00001>
<name type="string">Chapter 1</name>
<subchapters>
<subchapter_00001>
<name type="string">Subchapter 1</name>
<refpages>
<refpage_00001>
<keywords type="string">this text for the first article</keywords>
<listlink type="windowreference">
<class>reference_manualtextwide</class>
<recordname>library.mymodule.entries.chapter_00006_referencema nual.chapters.chapter_00001.subchapters.subchapter _00001.refpages.refpage_00001</recordname>
</listlink>
<name type="string">Article one</name>
<text type="formattedtext">
<p>This text for the first article</p>
</text>
</refpage_00001>
<refpage_00002>
<keywords type="string">some formating samplesonetwothreeheadingsample of chat frameikaelthis is awesome</keywords>
<listlink type="windowreference">
<class>reference_manualtextwide</class>
<recordname>library.mymodule.entries.chapter_00006_referencema nual.chapters.chapter_00001.subchapters.subchapter _00001.refpages.refpage_00002</recordname>
</listlink>
<name type="string">Article two</name>
<text type="formattedtext">
<p>Some <i>formating </i>samples</p>
<list>
<li>One</li>
<li>Two</li>
<li>Three</li>
</list>
<h>Heading</h>
<frame>Sample of chat frame</frame>
<frame><frameid>Ikael</frameid>This is awesome</frame>
</text>
</refpage_00002>
</refpages>
</subchapter_00001>
<subchapter_00002>
<name type="string">Subchapter 2</name>
<refpages>
<refpage_00001>
<keywords type="string">some text</keywords>
<listlink type="windowreference">
<class>reference_manualtextwide</class>
<recordname>library.mymodule.entries.chapter_00006_referencema nual.chapters.chapter_00001.subchapters.subchapter _00002.refpages.refpage_00001</recordname>
</listlink>
<name type="string">Article three</name>
<text type="formattedtext">
<p>Some text...</p>
</text>
</refpage_00001>
</refpages>
</subchapter_00002>
</subchapters>
</chapter_00001>
<chapter_00002>
<name type="string">Chapter 2</name>
<subchapters>
<subchapter_00001>
<name type="string">Subchapter 3</name>
<refpages>
<refpage_00001>
<blocks>
<block000>
<text type="formattedtext">
<p>Here is regular <b>formattedtext </b>entry defined inside blocks-node. This is nothing special, just text</p>
</text>
</block000>
<block001>
<align type="string">right,left</align>
<blocktype type="string">image</blocktype>
<caption type="string">Image is missing because it cannot be added programmatically</caption>
<frame type="string">sidebar</frame>
<size type="string">200,50</size>
<text type="formattedtext">
<p>Sidebar text</p>
</text>
</block001>
<block002>
<align type="string">left,right</align>
<frame type="string">text5</frame>
<text type="formattedtext">
<p>First column is <b>formattedtext </b>and is placed here. It doesn't have any decorations. Just <b><u>formaated text</u></b></p>
</text>
<text2 type="formattedtext">
<p>Second column <b>formattedtext </b>using <b>text5 </b>frame. This column is automatically enclosed in a sidebar frame image.</p>
</text2>
</block002>
</blocks>
<keywords type="string">next we have some samples how to define reference manual block datacurrent fantasy grounds is limiting that images cannot be written included programmatically so you need setup those manually</keywords>
<listlink type="windowreference">
<class>reference_manualtextwide</class>
<recordname>library.mymodule.entries.chapter_00006_referencema nual.chapters.chapter_00002.subchapters.subchapter _00001.refpages.refpage_00001</recordname>
</listlink>
<name type="string">Article four</name>
<text type="formattedtext">
<p>Next we have some samples how to define reference manual block-data</p>
<p>Current Fantasy Grounds is limiting that images cannot be written/included programmatically so you need to setup those manually</p>
</text>
</refpage_00001>
</refpages>
</subchapter_00001>
</subchapters>
</chapter_00002>
</chapters>
<importedpage type="number">1</importedpage>
<librarylink type="windowreference">
<class>reference_manual</class>
<recordname>library.mymodule.entries.chapter_00006_referencema nual</recordname>
</librarylink>
<name type="string">Reference manual</name>
</chapter_700_referencemanual>


17065

Thanks for any replies in advance..just starting my journey on writing Reference Manuals.

GB

[Nickademus]

You are referencing a location for the pages. Can we see the <library> contents?

<recordname>library.mymodule.entries.chapter_00006_referencema nual.chapters.chapter_00001.subchapters.subchapter _00001.refpages.refpage_00001</recordname>

[Nickademus]

Looking at that code, it has a very weird design. The reference entries are in the library section? The <library> is usually only for the library list. References are usually put in a <reference> section.

Here. This is a reference manual template. It is filled with placeholders (i.e. xxPage, xxKeyword). The format has three main sections: the <reference> where individual pages go, the <lists> where the code for the heading tree (that appears in the left side of the window), and the <library> which only houses the link to open the reference manual. Compare this with what you are using; it might make more sense.

<?xml version="1.0" encoding="iso-8859-1"?>
<root version="1.0" release="10">
<reference>
<!-- ** Reference Manual ** -->
<xxManualName>
<xxPage>
<name type="string">xxPageName</name>
<!-- Optional leading/solitary text -->
<text type="formattedtext">xxText</text>
<blocks>
<xxBlockName>
<blocktype type="string">text</blocktype>
<text type="formattedtext"><p>xxText</p></text>
</xxBlockName>
</blocks>
</xxPage>
</xxManualName>
</reference>
<lists>
<!-- ** Reference Manual ** -->
<xxManualIndexName>
<chapters>
<xxChapter>
<name type="string">xxChapterName</name>
<subchapters>
<xxSubchapter>
<name type="string">xxSubchapterName</name>
<refpages>
<xxPage>
<listlink type="windowreference">
<class>reference_manualtextwide</class>
<recordname>reference.xxManualName.xxPage</recordname>
</listlink>
<name type="string">xxPageName</name>
<keywords type="string">xxKeyword xxKeyword</keywords>
</xxPage>
</refpages>
</xxSubchapter>
</subchapters>
</xxChapter>
</chapters>
</xxManualIndexName>
</lists>
<library>
<xxModuleName>
<name type="string">xxModuleName</name>
<categoryname type="string">xxCategory</categoryname>
<entries>
<!-- ** Reference Manual ** -->
<id-00001>
<librarylink type="windowreference">
<class>reference_manual</class>
<recordname>lists.xxManualIndexName</recordname>
</librarylink>
<name type="string">xxManualName</name>
</id-00001>
</entries>
</xxModuleName>
</library>
</root>

You can also download the Unearthed Arcana module from the DMsG and open it to view a completed reference manual using this template.

[GunbunnyFuFu]

I'll take a look at that module, Nickademus. I'm working on getting the code moved around and such..It's the first real bit of work that I coded up, and all I had to copy off of was a few of the older Savage Worlds modules.

As I'm still new to this, pardon any idiotic questions from me. Should the reference manual be in the reference section, and not the library? I'm assuming there is a bit of XML code in the Library that points to the reference manual, so that it can be seen in the library? (IE the link that says reference manual..click that and it opens the reference manual proper, whose data is stored in the <reference> section)

Thanks for helping me clear it up, Nickademus.

[GunbunnyFuFu]

Here's the remainder of the library section...I've noted that I had library.mymodule.entries... and it should have been library.srttlpg.entries.. It didn't make a difference in what was displayed, sadly.

17066

[Nickademus]

As I'm still new to this, pardon any idiotic questions from me. Should the reference manual be in the reference section, and not the library? I'm assuming there is a bit of XML code in the Library that points to the reference manual, so that it can be seen in the library? (IE the link that says reference manual..click that and it opens the reference manual proper, whose data is stored in the <reference> section)

There is a bit of freedom when designing modules, so unfortunately there is no standard to follow. I use a layout similar to many of the PF modules that I used to learn to make modules. The thing to remember is that a 'reference manual' is just one kind of asset that can be in a module. The same module might hold classes, feats, skills, races, spells, etc. (You will see precisely this in my UA module.) So the reference manual doesn't go in any one section. Parts of it go in each of the sections. Here is a breakdown of the format that I, and others, use for modules:

<reference>: this section holds the data assets. This way only one copy of each asset exists and can be linked to from anywhere else in the module. The assets can be listed in a straight list, or nested into elements. For reference manuals, each of the pages should be stored in the <reference> sections since each page is a unique asset. I group my pages together in an element called <xxManualName> inside the <reference> element. Replace the placeholder xxManualName with a single word that represents your reference manual.

<lists>: this section holds the various lists that a user will navigate to get to an asset they want. There is little to no data here other than what is necessary to pull up the next list. For reference manuals, the entire heading tree will be in the <lists> section, with nested chapters, subchapters, and pages. Each page will have a link to the page data in the <reference> section (reference.xx.xxPage).

<tables>: this section holds the data for all the tables that can be rolled on. Technically they should be in the reference section, but I don't consider the tables to be game assets. Rather they are aids, and the code can get long. So I put them in their own section at the bottom.

<library>: this section is required by FG and is used to create the list of links inside the Library window. No other information should be put here. For reference manuals, use the code above to initiate the reference manual window, swapping the placeholders with appropriate names.

[Nickademus]

Here's the remainder of the library section...I've noted that I had library.mymodule.entries... and it should have been library.srttlpg.entries.. It didn't make a difference in what was displayed, sadly.

17066

Still not seeing the section entries.chapter_00006_referencemanual.chapters.cha pter_00001.subchapters.subchapter_00001.refpages.r efpage_00001 in that image. You should either try to remodel it to be like the code I provided or post a gutted version of the module here for us to look through. The links are going all over the place and screenshots will be difficult.

[GunbunnyFuFu]

Nickademus,

Thanks for the very, very helpful information! I'm in the process of gutting/remodeling to be like the code you provided. I'll certainly need to move most of my assets to the Reference from the Library, as most of my library contained the various edges, skills, hindrances, and whatnot that should be in the reference section. Again, thanks a million.

Chris/GB

[Ikael]

The structure of your sample XML file is fine. There is no need to separate it into different sections. What Nickademus described is just cosmetic XML re-structuring and will not affect output anyhow, just how you can read your XML yourself.

That said, the XML is from SW Enhanced Library extension's Content Importer sample, isin't? Why not continue building your reference manual using that tool. It's lot faster when you learned the markup and don't need to worry about XML structure and you can focus on content creation instead. Personally I am able to convert 100 pdf pages worth of content in just 8 hours using the tool (including all FG content like drag and droppable edges, gear, tables, npcs etc). If I would do just text I could do it in few hours.

If you insist doing XML the short answer is to replace recordname with ..

[GunbunnyFuFu]

Ikael,

That is exactly what it is. I already had 10k lines of code into my document (and had everything working) before I decided to tackle the Reference Manual. I would love to become as proficient as you in using the Content Importer, and it's on my short-to-do list, but I was trying to avoid having to re-enter all the data.

Chris/GB

[Nickademus]

If you insist doing XML the short answer is to replace recordname with ..

This is how you would fix it. Each of the library entries seem to hold their own data and the '..' recordname would access it. I was starting to get that feeling but I wanted to see the chapter_00006_referencemanual entry to be sure.

[Ikael]

As you have done the content already using SW Enhanced Library (can be deducted from the screenshot) you can use ALT drag-drop to convert your existing content into required markup format. Just open the Content Importer and your existing module, hold ALT down and drag from page link to Content Importer's source view to generate markup from the page. No need to type the same content there twice when you use tool's potential. Trust me, I have created The Last Parsec modules and created reference manual version of those this way. It did not take more than few hours.

[GunbunnyFuFu]

Nickademus,

I assume that having each library entry holding its own data is not an ideal way of doing it? I believe it was the...Sci-Fi companion along with the Hell on Earth modules that I looked at in order to build my own. It's a piece of Frankencode...bits from here, bits from there, etc.

Ikael,
The only portion that was parsed out using the SW Enhanced Library is the reference page stuff. Everything else was hand-coded in using XML. Is that an issue with the content importer or is it still doable without all of it being done in the content importer?

Chris/GB

[Ikael]

My recommendation is the create the content importers markup into text file outside FG. You can use the Alt drag drop to create content and copy-paste it from FG to the text file and then when you want to preview your creation, copy paste the whole text files content into tool's Reference Manual Preview (either use the slash command or the tool's source view) . Its lot faster than dealing with xml yourself.

I am writing this from my phone, but if you need more detailed how-to best practises from using near-full potential of the tool just let me know and I can write more detailed step to step instruction how I do it myself

[Bidmaron]

Ikael, why isn't your content importer in areas other than SW? It sounds general enough to be used anywhere?

[Ikael]

Is that an issue with the content importer or is it still doable without all of it being done in the content importer?

Chris/GB

Not an issue. You can still use the content importer and avoid inputting everything twice.

[Ikael]

Ikael, why isn't your content importer in areas other than SW? It sounds general enough to be used anywhere?

I have created generic working version of it for CoreRPG but A) Since it doesn't have all Enhanced Library features, I am not happy about it yet B) don't have time or motivation to continue that version since I am full SW user myself C) you still/already can use the tool to create reference manual for any CoreRPG ruleset but you are required to use SavageWorlds ruleset to use the tool and need to manually remove SW dependency from outputted module (removal of single line from the module).

[Bidmaron]

Thanks, Ikael. Will remember that when I next want to work a module from PDF.

[Myrdin Potter]

I own the SW ruleset, so all I need to do to make a 5e reference manual is mark up a text file, use your tool and then change the ruleset to 5e from SW?

I still need to learn the relation between content in reference documents and the standard story entries. I want to recreate adventures in FG that look like books, like the way the WoTC modules look and not have to redo all the story entries again. There are som 3PP that have well put together books and I want to try and copy that.

[Ikael]

I own the SW ruleset, so all I need to do to make a 5e reference manual is mark up a text file, use your tool and then change the ruleset to 5e from SW?

I still need to learn the relation between content in reference documents and the standard story entries. I want to recreate adventures in FG that look like books, like the way the WoTC modules look and not have to redo all the story entries again. There are som 3PP that have well put together books and I want to try and copy that.

Yes, after you exported the module that you created with content importer you must edit module's definition.xml file and change ruleset value from SavageWorlds to whatever CoreRPG derived you need, such as 5e.

If you have existing commercial product and want to see how some reference page was created you can use the ALT drag-drop trick to convert that article into markup and see what was defined there. Personally I have used this a lot to see how some products defined articles with images and graphics.

There is not much difference between reference content and story entries. That are the same in database node level but reference content supports slightly more features such as embedded images

[GunbunnyFuFu]

Ikael,

I would certainly use (and appreciate!) any documentation to show how Content Importer works, as most of what I'm doing now is within Savage Worlds anyway, though there is 5e stuff I'd like to tackle as well.

Thanks!

GB

[Trenloe]

General info on the reference manual structure here: https://www.fantasygrounds.com/wiki/index.php/Reference_Manuals

Info on module data structure and best practices: https://www.fantasygrounds.com/wiki/index.php/Data_Structure_Overview_and_Best_Practices

[GunbunnyFuFu]

Thanks Trenloe for linking that! One question...it shows (for Savage Worlds) that reference.mundaneitems is in older rulesets, but not recommended in newer rulesets. Is there a newer reference scheme in place?

GB

[Nickademus]

I think that list is saying those are not recommended for 'new' rulesets, not 'newer', as in custom rulesets. This might be to avoid conflicts. If you are not making a brand new ruleset, then there should be no problem using that last list (in fact the 5E ruleset automation requires some of them).

[Ikael]

Thanks Trenloe for linking that! One question...it shows (for Savage Worlds) that reference.mundaneitems is in older rulesets, but not recommended in newer rulesets. Is there a newer reference scheme in place?

GB

reference.mundaneitems path is still supported by the ruleset, but the recommend path for common items is reference.items. Mundane items version is from SavageWorlds v3 ruleset times and after it was converted into CoreRPG derived ruleset the recommended path was changed to be the same as in CoreRPG

[GunbunnyFuFu]

Thanks Ikael! I'll go with that!

GB

[GunbunnyFuFu]

Would Cyberware fall under reference.items (i.e. it is a catchall), or should there be an actual reference.cyberware for it?

[Trenloe]

The main thing that the reference.xxxx path is going to impact is the auto population of the data in the "new" FG campaign data lists accessible from the sidebar. If the XML location doesn't match what FG is designed for then the data won't be shown. The best practices page mentions: "If different types of each record need to be tracked, we recommend using a "type" string field to differentiate, instead of using additional data paths." I'm not sure if "type" is specifically used in the Savage Worlds ruleset, the "catname" XML tag within each item record seems to be used to populate the "Category" filter in the campaign list, and the "group" XML tag in the item record populates the "Group" filter.

Here's an example from the Rippers Player Guide:

https://www.fantasygrounds.com/forums/attachment.php?attachmentid=17076

The XML is shown on the left - and the items use the reference.weapons DB location, which in the data structure overview page is listed as: "reference.weapons" = Items - Weapon (SW)" so we know that this will appear in the Items campaign list.

<catname type="string">Weapons</catname> determines what "Category" filter at the bottom of the campaign list will return this record, in this case "Weapons".
<group type='string'>Melee Weapons</group> determines what "Group" filter at the bottom of the campaign list will return this record, in this case "Melee Weapons".

[Ikael]

Would Cyberware fall under reference.items (i.e. it is a catchall), or should there be an actual reference.cyberware for it?

Cyberware should be defined to use path reference.cyberware
This is not documented anywhere but can be read from source codes (if you have access to them~ in case of Interface Zero, you have no luck since it is encypted). If you are not sure what path you should be use and you cannot access source code to check it, my recommendation is to create one sample record using SW Enhanced Library extension and exporting it~ exported module's xml is remastered to use correct/standard paths for all resources and there are plenty of those in case of SavageWorlds. If you didn't know you can create cyberware and many other resources if you have corresponding extension enabled with the SW Enhanced Library, ie. if you have both SW Enhanced Library AND Interface Zero OR Science Fiction Companion extension enabled at the same time you're able to create cyberware with the UI.

[GunbunnyFuFu]

Thanks again Trenloe! Reference.items it is!

GB

[GunbunnyFuFu]

Ikael,

I do have Interface Zero, which I purchased solely to look at the coding...only to find out it was encrypted. I'll try one with cyberware, and if that doesn't work, I'll go the .items route. I based most of my 1st conversion off of Sci-Fi Companion, as it isn't encrypted and I could see the XML layout to emulate.

I think I'll do the same with the various armor types..both power and robot armor possesses different attributes than body armor, and each one of those are defined separately in the Sci-Fi companion, though this is a very early convert and doesn't adhere to the new standards I would imagine.

[Moon Wizard]

I believe the paths are reference.cyberware and reference.modifications for the campaign lists added by Interface Zero.

Let me know if that doesn't work, and I can look it up when I get back to computer this evening.

Regards,
JPG

[Ikael]

I believe the paths are reference.cyberware and reference.modifications for the campaign lists added by Interface Zero.

Let me know if that doesn't work, and I can look it up when I get back to computer this evening.

Regards,
JPG

Those are the paths, except that Interface Zero doesn't introduce modifications, that's only in Science Fiction Companion. Both extensions define cyberware using that path and they have custom masterindex list to display cyberware. If that path is not used then they won't list in that custom list.

Do not go with items path as there are some logic that depends on the exact path

[GunbunnyFuFu]

Ikael,

I'll go with the cyberware path defined as Sci-Fi companion. Thanks!

GB

[Ikael]

Ikael,

I would certainly use (and appreciate!) any documentation to show how Content Importer works, as most of what I'm doing now is within Savage Worlds anyway, though there is 5e stuff I'd like to tackle as well.

Thanks!

GB

Check the newest FG v3.2.2 version of the SW Enhanced Library extension (https://www.fantasygrounds.com/forums/showthread.php?35607-SW-Enhanced-Library-for-Fantasy-Grounds-v3-2-2&p=308145#post308145). It includes built-in user manual about Content Importer tool. No need to download separate module, just get that extension and click the Question-mark icon in Content Importer window's top right. The user manual itself is dynamically generated from markup included in the extension and it includes lots of samples

[Bidmaron]

Thanks, Ikael.

[GunbunnyFuFu]

Thank you Ikael!

[Baufrin]

My recommendation is the create the content importers markup into text file outside FG. You can use the Alt drag drop to create content and copy-paste it from FG to the text file and then when you want to preview your creation, copy paste the whole text files content into tool's Reference Manual Preview (either use the slash command or the tool's source view) . Its lot faster than dealing with xml yourself.

I am writing this from my phone, but if you need more detailed how-to best practices from using near-full potential of the tool just let me know and I can write more detailed step to step instruction how I do it myself

I think this should be done for us new guys to FG I would love to see the best way to make a reference manual using that tools with detailed write ups for newbies. Everyone has been great trying to help but that would really be the best.