Customising bullet lists symbol issue

[ChrisTMH]

Hello again,

I'm attempting to change the bullet symbol used for unordered lists. I would like to change it to the following symbol:

[url=http://unicode-table.com/en/25A0/]http://unicode-table.com/en/25A0/[/url]

I use the HTML code, but the symbol does not appear on the PDF. I'm overriding the var correctly as I've tested it with a simple subtraction symbol (-) and that works.

As far as I can see, I can't get any of these to work, so I don't have any options here

[url=http://unicode-table.com/en/search/?q=black+square]http://unicode-table.com/en/search/?q=black+square[/url]

Cheers

Reply

[Derek Read]

I'm not sure what portion of the DITA Open Toolkit you are changing, but if the hyphen change is getting into the PDF but other characters are not then your issue is a font-embedding problem.

The PDF standard supports a limited set of default fonts and these fonts do not support Unicode (they do not have the glyphs required to display the vast majority of Unicode characters, they only contain glyphs for the equivalent of the Latin1 range). To display these characters you need to embed a font, or the specific glyphs from a font, into the PDF.

To do that you need to edit the xep.xml and possibly also the font-mappings.xml files (assuming the deliverable you are using to produce PDF is using RenderX XEP to generate PDF). Some information on that is located here: http://forums.xmetal.com/index.php/topic,366.0.html

That's an old post however, so if you're using a version of XMetaL Author Enterprise that is newer than 8 then the location of the DITA OT will be different. See the end of the following thread where it talks about the location of the DITA OT for version 9 and up: http://forums.xmetal.com/index.php/topic,237.msg8786.html#msg8786

Reply

[ChrisTMH]

Ok I'm really not sure where to go from here. Erm, I have found a symbol in a MS font pack which contains the symbol I want to use, but I am not sure where to go from here.

Basically, I want to have “Arial Unicode MS Standard” available, and to grab a symbol from there. I believe this is what you need to do when you find a Unicode character character you want, but again, I have no idea how XMetaL is doing this.

So how would I embed a font or embed a specific glyph from a front exactly? I've looked at the topic you linked me to, as well as http://forums.xmetal.com/index.php?topic=1155.0 and http://forums.xmetal.com/index.php/topic,116.0.html but I'm still none the wiser.

Reply

[Derek Read]

If you just need one character then you can embed just that one character from the font into the PDF (which would keep the size of the PDF down). The changes required are virtually the same, with one directive being different (embed the whole font vs embed only characters needed by the current document). The only time you would really need to embed the whole font (I think) would be for a PDF that you expect the reader to be able to edit and enter their own characters.

If you can let me know which version of the software you are running and which deliverable you are using to generate your PDF I can point you in the right direction. At least two files need to be modified but they will be different and in different locations depending on that info.

Reply

[ChrisTMH]

If you just need one character then you can embed just that one character from the font into the PDF (which would keep the size of the PDF down). The changes required are virtually the same, with one directive being different (embed the whole font vs embed only characters needed by the current document). The only time you would really need to embed the whole font (I think) would be for a PDF that you expect the reader to be able to edit and enter their own characters.

If you can let me know which version of the software you are running and which deliverable you are using to generate your PDF I can point you in the right direction. At least two files need to be modified but they will be different and in different locations depending on that info.

Thanks for your help with this, much appreciated.

XMetaL author enterprise version 10.0.0.074
DITA version 1.2
To generate the PDF, we specialise on the “com.xmetal.xmfo” plugin

Cheers

Reply

[ChrisTMH]

Bump

Reply

[Derek Read]

Here'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).
   
       left
   

Paste that whole thing into custom.xsl after the (because that's what imports all the other files and we want to override anything in the imported files, not have the imported files override what we set here). Then, for testing only, change the colour of the text to red (which hopefully will be the bullet if we guessed correctly). I include font-family here as well because eventually we'll do that too if this works.

   
       left

Sans
       red
   

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):

Code2000

11. Reopen custom.xsl and change the font-family from “Sans” to “Code2000”:

   
       left

Bullets
       red
   

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):

1.5em
0.5em

0.5em
0.5em

Reply

[ChrisTMH]

Here'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).
   
       left
   

Paste that whole thing into custom.xsl after the (because that's what imports all the other files and we want to override anything in the imported files, not have the imported files override what we set here). Then, for testing only, change the colour of the text to red (which hopefully will be the bullet if we guessed correctly). I include font-family here as well because eventually we'll do that too if this works.

   
       left

Sans
       red
   

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):

Code2000

11. Reopen custom.xsl and change the font-family from “Sans” to “Code2000”:

   
       left

Bullets
       red
   

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):

1.5em
0.5em

0.5em
0.5em

Fantastic, thank you for the guide. I've successfully implemented this now.

One final question: if I find a symbol I would like online, say from fileformat.info, is there an easy way to find out which Windows font pack that symbol is embedded within?

Reply

[Derek Read]

Interesting that you mention that website. It is a very useful and well-organized resource that I've used over the years for various things. They link to fonts that contain a particular character (glyph for that character) on the page for each character. Look for “Fonts that support U+####”. Or if you know the hex value you can create your own URL, example: http://www.fileformat.info/info/unicode/char/2605/fontsupport.htm

Reply

[Author]

Posts