Home › Forums › DITA and XMetaL Discussion › Customising bullet lists symbol issue › Reply To: Customising bullet lists symbol issue
Derek Read September 7, 2016 at 11:39 pm
Reply to: Customising bullet lists symbol issue
September 7, 2016 at 11:39 pmHere's most of what it took to figure this out (minus a lot of testing of dead-ends that I have not listed).
Hopefully this process will help you with resolving this particular issue, but also help pick apart the DITA OT and figuring out what it does.
My #1 tool for working with the DITA OT is a good text search tool (or a good text editor that has a good text search feature).
#2 is some level of understanding of XSL, XSL-FO and the specifics of RenderX XEP (or Apache FOP or Antenna House Formatter if you are using that instead).
1. Search the subfolders in the DITA OT for the word “bullet” and hope that it exists in a comment or something in one of the file that would be related to PDF output. Turns out that the internationalization portions of the PDF output (for DITA OT 2.2) define a different character for different languages. For English the character specified is • There are two files included for English: en.xml and en_US.xml. The default for the DITA OT (if no xml:lang value is specified) is en_US.xml. How did I figure that out? More testing…Change line 125 in each file, one at a time, C:ProgramDataSoftQuadXMetaLSharedDITA_OT2.2pluginscom.xmetal.xmfocfgcommonvarsen_US.xml and en.xml and then generate a PDF to test each one. I used the letter “H” (could be any letter) because I thought there would be a good chance that the rest of the DITA OT would be specifying “normal” fonts that define glyphs for the alphabet and hopefully not a “wingdings”-like font.
2. After testing to see that “H” works change the value to some other character that doesn't render in the default PDF output but that does exist in a font I have. I chose a high code-point character (way outside the ASCII / Latin1 ranges) that will be obvious to spot if it shows up, the Unicode character “CIRCLED WHITE STAR” ✪ A glyph for it is defined in the fonts Code2000 and Arial Unicode MS (both of which I have on my machine). So, at this point I've just made the change and confirmed that it does not appear when I generate PDF output. I think I am where you are at this point: I've found where I can change the character but it isn't rendering in the PDF. Revert it back to “H” so that we can do some further testing (because, as with anything software related, it's best to only ever change one thing if possible).
3. The variable named “Unordered List bullet” defined on line 125 in en_US.xml also appears in this file (which I also found via searching the xmfo subfolders): C:ProgramDataSoftQuadXMetaLSharedDITA_OT2.2pluginscom.xmetal.xmfoxslfolists.xsl You don't need to do anything in there. However, I searched the rest of the files for that variable to check that it wasn't used elsewhere as well. What is useful to see in lists.xsl however, are the “attribute sets”. I found three: “ul.li”, “ul.li__label”, and “ul.li__label__content”. The DITA OT uses “use-attribute-sets” to call call an “attribute-set” that defines styling (for PDF output) and that could include specific fonts.
4. Search all files again for the following to see if any specific fonts are set: “ul.li”, “ul.li__label”, and “ul.li__label__content”. The file that might set that up (where they do appear) is C:ProgramDataSoftQuadXMetaLSharedDITA_OT2.2pluginscom.xmetal.xmfoCustomizationfoattrsxm-cfglists-attr.xsl. There aren't any fonts set up in there, which tells me that those are all inheriting their font family from some parent block. So I think we have two options: a) try to figure out how far up that goes and then set a different font there. b) Try to figure out which of those three things is containing the bullet character and just set a different font only for that. I choose the latter as I think that will be easier (and less likely to cause problems elsewhere, given that if we change something higher up that is likely to cascade down into some other area and mess something up there).
5. So, in lists-attr.xsl is where we might set up a font. To be clean though, it would be best to put that in this file, effectively as an override:
C:ProgramDataSoftQuadXMetaLSharedDITA_OT2.2pluginscom.xmetal.xmfoCustomizationfoattrscustom.xsl
From the lists-attr.xsl file I copy this (again, I only know that this is where I need to set a font through additional trial and error on the other ones in there).
Paste that whole thing into custom.xsl after the
Note: At this point, since we're not really messing with fonts and font embedding yet, you need to have left the character as an “H” in the en_US.xml file.
Generate output and check to see that your unordered lists have a red “H” next to them for the bullet.
If you don't see a red “H” then go back and check for typos, file paths, etc, and test again.
6. Now that that's working change the “H” to a character that is in a font that you have. In my case I will use Code2000 and ✪ which means editing line 125 in the en_US.xml file.
7. Use the Windows charmap.exe tool to confirm that the font you want to use contains the character. In my case that means opening charmap.exe, selecting Code2000 as the font, then entering 272a as the hex value. I see the character so it is in there. If after entering the hex value and pressing enter the UI scrolls to a different character then the font doesn't have your character (charmap.exe scrolls to the nearest character that it does have instead).
8. Now you need the actual font name. Using Windows Explorer, open your Fonts folder, which is usually C:WindowsFonts. Find your font. Check to see that the font name matches exactly what you saw in charmap.exe. Font's often come in groups that include separate files for italic, bold, etc. Make sure you are selecting the right one. Right click on it and look at Properties to obtain the filename. In my case, for Code2000, the font's name is actually “Code2000 Medium” and the filename is “CODE2000.TTF” (the full path is C:WindowsFontsCODE2000.TTF, which might be needed if your Fonts folder is in a non-default location).
9. Edit this file: C:ProgramDataSoftQuadXMetaLSharedrenderxxep.xml
Locate the following line:
Inside that section add a new child element “font-family” that tells RenderX XEP where to locate your font:
10. Edit this file: C:ProgramDataSoftQuadXMetaLSharedDITA_OT2.2pluginscom.xmetal.xmfocfgfofont-mappings.xml
Locate the following line:
Inside that section add a new child element “logical-font” and name it “Bullets” and tell the DITA OT every time you see that to use the “Code2000” font and use it for all characters (which in our case is only one character):
11. Reopen custom.xsl and change the font-family from “Sans” to “Code2000”:
12. Generate output. If you don't see your character in red then go back and check for typos, file paths, etc, and test again. You can also check to see if the font is being embedded by right clicking on the PDF and selecting “Properties” then the “Fonts” tab. That won't help you much except to show you that the font is (probably) not being embedded (and if it isn't then the character won't be visible).
Once it works remove the “color” attribute so that it appears black (if you want).
13. I have further modified the style in custom.xsl to add additional space after the bullet, so that it doesn't butt up against any content, by adding the following to the custom.xsl (which duplicates then modifies the attributes from lists-attr.xsl):
