Data Mentor Lesson 1
Hi Everyone,
My name is Andrew Maitland, I've been involved with PCGen officially since around 2006, I've been using the program and coding since around 2002. While I might not know everything there is about the code, I do have a lot of experience coding up books, helping several people over the years and assisting in discussions about improving the pcgen code base. You're joining up at an exciting time, if you aren't aware of these changes, I'd highly recommend you sign up on the pcgen experimental yahoo group and start following those conversations. We're literally on the cusp of a new era for Data Team monkeys.
Just for references - http://wiki.pcgen.org/FACTSET_Token and http://wiki.pcgen.org/index.php?title=FACT_Token
If you can't follow what that means, it's basically the Data team will be able to make new "Tokens" on the fly without relying on the code team and use them immediately as desired. As I said, this is a very exciting time to learn. (The code team is excited since that would make 30 Newtag requests obsolete!)
Let me know what time and day(s) are good to connect with you 'online'. Skype and IM are tools I'd like to use to personalize our lessons. Today is just a getting to know you, introduction to tools and an overview of PCC files. Please have the items requested installed on your computer so we can jump right into the meat of things.
First things first, Data Monkeys fall under the team umbrella of 'Content' - that is to say that our team is responsible for delivering usable content to the program and user in the form of Data Sets (Source Books) using PCC and LST files, documentation and output sheets. http://wiki.pcgen.org/Content
The content team is composed of three subteams - Data, Output Sheet and Documentation. Data - creates and maintains the data sets - LST & PCC files. OS - Creates and maintains the outputsheets which use htm (for web browsers), txt (forums) and pdf - which uses fop and freemarker (currently this is accomplished using xml, fo and xslt). Freemarker will reduce the complexity here and will allow us to use the prosed new 'tokens' we set by FACT and FACTSET. Docs - Handles all the program documentation - fixing typos, and entering new tokens.
We require cooperation from the code team to get 'Tokens' or 'Tags' that the program will understand and translate our information to make the character work. Once a token is created, it's entered into the documentation where we can reference the token's functions and limits. It's key to understanding that certain tokens are "Global" meaning you can use them in any file type, or local to specific file types. An example of a Global token is 'BONUS:COMBAT|BASEAB|classlevel("Fighter")', a local token would be 'ASPECT:NAME|Looks good to me.' With that understanding, I know that ASPECT only works in the Ability File Type, where BONUS will work everywhere. HOWEVER, there are exceptions to all the rules, which can make instructing new people in the limitations difficult. For the sake of Argument, assume that SPELL, EQUIPMENT and EQUIPMOD file types are special and will cause you problems if you try to use 'Global' tokens in them. We'll cover that more in-depth when we discuss those files.
RESOURCES:
The greatest resources for the data team are on our wiki - http://wiki.pcgen.org/Data
I would ask that each of you peruse this page - http://wiki.pcgen.org/Data_Team_Tools
Select or find a TEXT EDITOR for your operating system. I use Editplus, but I've also used Notepad++ and Crimson/Emerald Editor. Find one that suits you.
PRO TIP: Editors are a powerful tool, you find the one that feels comfortable to you. If one you use is not in that list, don't fret. Just use the tool you know and like.
Editors can have powerful Find/Replace functions. In Editplus, it has the ability to store a list of nameable Find/Replace commands that I often use. It also have Multiple Line Find/Replace functionality. Try to get an editor that has those extra features. A common one you'll like is the Column Select - ALT-LEFT CLICK - drag down and instead of selecting a row like normal, you'll grab just a column you select.
Since the project uses SVN and GIT I would ask you grab one or the other Client. The Pro with using SVN is you'll have immediate results in our repo. GIT has to go through our gatekeeper (Henk). If you don't have a preference just use SVN for now. (Note I've listed several SVN clients on the wiki).
This has information on how to set up SVN (Subversion) - http://wiki.pcgen.org/Subversion_Setup
///\\\ \\\///
At this point you should have the following set up on your system:
1) Text Editor 2) Repository Access Method (SVN or GIT)
Next, we'll want to take advantage of SYNTAX HIGHLIGHTING. If your Text Editor has a listed Syntax Highlighting or Syntax Coloring, let me know. We'll get you an updated copy of it.
Syntax Highlighting is a VERY useful tool. At a glance you'll be able to determine whether your syntax is spelled correctly. Using PrettyLST to line up your columns will make bulk "eyeballing" a lot easier. Your editor will allow you to personalize the colors. My personal preferences for the editor is to do a subtle blue or green highlight for the line I'm on. I also use the bracket matching (Great for making sure formulas are enclosed properly). You'll want to have hidden characters of 'TAB Spaces' and 'SPACE' visible. Speaking of settings, the default TAB SPACING is 6 due to how PrettyLST was set up.
PrettyLST is another handy tool, once set up, it's a simple program to use. It does require you to install PERL to use though. You are not required to grab it, but as a Data monkey, I find it's value immeasurable when I'm working on books and getting those cleaned up. It also has a limited error detection capability, but as each new revision of pcgen comes out, those capabilities become less necessary. (As a rule, the code team does a fantastic job of improving the error detection capabilities).
Now that we've gotten you set up, let's put it to use.
If you have not already done so, download a copy of the repository to your hard drive (have 500+ MB available for this use).
The link will depend upon you: for a DOWNLOAD ONLY (svn://svn.code.sf.net/p/pcgen/code/Trunk)
Eventually, you should have made an SSH key, and copied the public portion to your user id on Sourceforge (Please do that, if you need help, contact me and I'll help you through that process - instructions are on the subversion setup wiki page)
If you have your account set up, and I've given you access (Email me your user Id - it's all lower case) you'll use this link to grab the repo: (svn+ssh://USERNAME@svn.code.sf.net/p/pcgen/code/Trunk)
Note that 'USERNAME' is your SF user id.
Git will use a different link, if you prefer GIT use the GIT instructions provided on the Subversion set up page instead.
That will give you TWO important locations, besides access to our working development line: pcgen/data and content/notfordistribution (referenced from this point forward as NFD)
The pcgen/data is the active development for ALL existing data sets - you make changes and upload them they will appear in the next release.
WARNING: Only volunteers with permission are allowed to edit 'core' sets. That would be the Core Essential/Core Rules in Pathfinder, RSRD for 35e, SRD for 3e, MSRD for Modern, etc. These sets are the foundation for all lower sets reliant on them. Break these books and you break an entire system. As a rule, only the Content Silverback or Data 2nd can grant permission to alter those sets. Otherwise, only Data Chimps can freely make changes to those sets. (You are considered a Data Lemur when you join the pcgen project).
Also a note about our development line, we have some fairly extensive "unit tests" - things that are constantly run against changes, if your change impacts those changes, the CI (Continuous Integration) test (aka Jenkins) will notify you and the experimental group. The two outcomes of this is to review the change and see if the outcome is correct. (We'll update the test if this is a correct outcome). If not, then the monkey needs to make the necessary changes to fix the issue.
content/NFD is where the data monkeys store our works in progress (Books). The only exception to this is if you are working with a publisher on a pre-release project and have signed a NDA (Non-Disclosure Agreement). NOTE: NFD sets ARE not monitored by the CI tests.
Okay, lots of information there, hope you're still with me. If you need, take a break.
<Isn't email great?>
If you took a break welcome back...
I'll be wanting to do these little learning projects in live session, but let's give you something to read/review.
PCC FILES
I made a video about PCC files. Understanding the basics of this file is key to a successful data monkey. Boiled down, the PCC file is the ONLY thing that interacts with PCGen at the program start up. The PCC file identifies itself by a unique name (CAMPAIGN:x) Do not ask me why they named it 'CAMPAIGN' instead of 'BOOKNAME'. Anyways, CAMPAIGN:x HAS to be a unique name among all the other existing PCC. It does not matter if it's a different GAMEMODE, each must be unique. The nice thing about PCC files is they accept 'KEY' which means you can do things like this:
CAMPAIGN:A Really fantastically long name, including normally illegal characters such as commas: including colons and other fantastic things.
KEY:My Book Name
This means the Unique ID is "My Book Name" but the User will see "A Really fantastically long name, including normally illegal characters such as commas: including colons and other fantastic things."
Which is great news for you and me, cause if we require this book in another set we can require it like this:
Method 1: PRECAMPAIGN:1,My Book Name
Method 2: PRECAMPAIGN:1,INCLUDES=My Book Name
As a matter of personal preference I prefer the INCLUDES= syntax with Method 2. This makes inclusion via a master grab better. As Pathfinder has grown, that function has become a necessary facet to building more complex interactions.
Now, I mentioned that PCGen only interacts with the pcc file. When the file is added and loaded, the file references in the pcc are taken by pcgen and loaded in order of rank and then items that duplicate are checked against a sourcedate and the newest one is used (IF the preference option is turned on) if not, then it's random which will win.
Just think of the PCC file as the master file to handle everything else. We don't spend much time dealing with PCC files, but it's crucial to understand the role and how to make it work to avoid consternation and frustration in the future.
PRO TIP: PCC File Changes will not be noticed by pcgen if made while the program is on! The pcc files are stored in memory during program start up, any changes made after the program is on will not be grabbed until you reload the program completely.
The Data team has come up with several standards, like this rule for pcc file grab and file names. For ALL file names we are to use only 'lower case' and 'underscores' to connect words. No Spaces or Capital letters.
Another rule - the PCC file token is singular, but our naming standard for the files themselves is in a plural format any add-on name is singular. The only exception is 'equip' or 'equipment'. Each file name has this format: "abb" abbreviation/abbreviated for of the source. Some sources will have known abbreviates 'PH' for Player's Handbook, DMG for Dungeon Master's Guide, etc. When known we should use that abbreviation. Following the 'Abb' we want the File Type, feats, classes, kits, companionmods, etc. We always should use the file type naming. It signifies the function and format of the file.
Do not worry about file names not being unique. They must be unique only to the folder they belong too. Only the PCC CAMPAIGN name must be unique. File names are not under that requirement. You might end up with two files with the same name, as long as they are in different folders, you can ignore it.
Examples of these practices:
"FILE:abb_type_add-on.lst"
CLASS:abb_classes.lst ABILITY:abb_abilities.lst ABILITYCATEGORY:abb_abilitycategories.lst
- abb-plural-singular
WEAPONPROF:abb_profs_weapon.lst ARMORPROF:abb_profs_armor.lst
The team does have a standard format for all file naming, and the appropriate add-ons. Please adhere to that at all times. Some people might ask "Why?"
If you name your file this: abb_Classes.lst <-- Note the capital 'C' in Classes.
and the pcc has this: CLASS:abb_classes.lst <-- No Capital 'C'
It will NOT load the file. PCGen pcc file calls are CASE SENSITIVE. Which is why we maintain a lower-case rule at all times.
Now that we've covered the basics, your simple homework assignment is to see about making a single pcc file that will load a feat and class file. If you want to try your hand at the next material we will be covering, you may. This is extra credit. If you don't know how to do this, it will be covered in our next session...
EXTRA CREDIT:
Create a class called 'LST Monkey':
LST Monkey BAB Progression is Good (1 each level) Save Progression good for all three. Hit Dice is 12
At 3rd level the monkey will get a feat for free called 'Banana Throw'
The Feats I want are:
Banana Throw [General] You are adapt at using bananas as deadly missiles Prerequisites: 3rd Level LST Monkey Benefit: Any banana you throw is treated as proficient and deals 1d10 damage.
Banana Focus [Combat] Your bananas are more accurate Prerequisites: Banana Throw Benefit: You gain a +1 to hit with Bananas
Our next online meeting will be determined by your respective schedules. Also, I'm learning from you as this is the second time I've taken on a mentoring role. Your feedback and participation will be key to your over-all success.
Cheers, Andrew Maitland
