Giters

alan-if / alan-docs

Alan IF Documentation Project

Home Page:https://git.io/alan-docs

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Fonts Choice

tajmone opened this issue · comments

commented

This issue tracks and discusses choosing fonts for the PDF template:

  • Enable custom fonts in XSL FO template settings.
  • Choose a font for:
  • Include chosen fonts in repository:
    • TTF/OTF
    • Webfonts (not needed right now!)

When choosing a font for the PDF template, we need to check that the following criteria are met:

  • Project inclusion — The font's license should permit including the font file in this project.
  • Webfont — The font should also be available as webfonts, or its license allow converting it to webfonts and storing them in this project. This is so that we can use the same fonts for HTML-based documents (web pages, ePub, Mobi, etc.).
  • Style and weights — The font must also available in bold, italic, bold+italic variants.
  • ISO-8859-1 glyphs — All ISO-8859-1 characters must be present in the font's glyphs.
  • Unicode chars — Commonly used Unicode characters/symbols should be represented in the font.
  • Ligatures — Should the (non-monospace) font used in the main body of text should support ligatures?

Original Fonts in Manual

These are the fonts currently used in the Manual:

  • Pristina — A commercial font by International Typeface Corporation.
  • Garamond — Many free fonts are available, based on the original typeface created by Claude Garamont (c. 1510–1561).
  • Courier New — Although the font that comes installed with Windows OS is a commercial font by Microsoft, similar typefaces are freely vailable under many different names.

Use of italics in the above list indicates that the font should be available in the preinstalled fonts of most OSs.

Fonts Websites

  • Font Squirrel — a good website for fonts, with many fonts also available as webfonts, and there is also the Webfont Generator tool to convert font files to webfonts. Font Squirrel also provides useful license information for its fonts, and prevents any operations that might violate the font's license terms.
  • Google Fonts — Huge fonts collection, with many options and tools to customize fonts.
commented

@thoni56, in these last two days I had a chance to play around with fonts in the PDF toolchain. Adding custom fonts isn't complicate at all, the latests versions of FOP make it much easier than in the past.

Limited Monospace Font Choices

What I do realize though is that the fonts choice is not actually as broad as I initially thought, due to the fact that we need the font to be also available in bold, italic and bold+italic version — which is not always the case in monospace fonts.

In different places of the Manual, verbatim code examples employ italics and bold, so we need a font that covers them — besides, the PDF template is going to be shared by other documents too, so we should strive to offer full font coverage of any styling needs, to avoid enforcing limitations on other documents.

Keeping an Eye on Code Ligatures

I've also been testing with source code font ligatures, both in code blocks and outside them. I'm not quire sure how Asciidoctor handles them, for some characters combinations that fall under the predefined Asciidoctor replacements are indeed shown with ligatures (e.g., -> to →), but this never occurs in source blocks, even when using a code font that supports ligatures.

In any case, I've updated the test docs with ligatures tests, so we can keep an eye open to check if and how these rendered in the various formats:

My reasoning is:

  • We don't want ligatures in Alan code examples, for the newby might be confused by glyphs like ⩽, ⩾ and ⇒, not knowing how to type them on the keyboard.
  • Different code fonts interpret differently the various comparison operators, which could introduce unwanted (and wrong) glyphs in the code examples.

So, basically the tests are intended to prevent ligatures in the documentation code examples and snippets.

Special Chars

On the other hand, we need to make sure that the font supports the required text ligatures and/or special Unicode characters. It's not always easy to understand when a special glyph is the result of Asciidoctor replacements or just a native Open Type ligature. The best we can do is to use these test docs to check manually that all characters are represented as expected.

Currently, quite a few special characters are not being represented correctly in the PDF documents — e.g. arrows, vertical ellipsis, and others. Asciidoctor can be painful to handle these chars, as using Unicode SML entities works in HTML output but not PDF. Anyhow, I'm sure I'm going to find a solution for that.

Upcoming Fonts Preview

I've managed to find a couple of monospace fonts that meet all our requirements, and I'll be publishing some PDF previews in a test branch in the coming days.

I'd like also to test a couple of fonts for the main body and titles. As mentioned, the original font used for titles is commercial, so we'll have to look for another one (besides, I find the original quite hard to read).

I'll take some liberty in fonts testing, if you don't mind, and once I have a set of previews to compare among we can decide which font combinations look better.

Before actually including any third party fonts in the project (even in test branches), I'd rather share PDF sample pages and/or screenshots, to avoid having to deal with licenses of fonts that we won't keep.

If you have any suggestions on font combinations for the document body and titles, please share them.

Also, you confirm the use of a Sanserif font for the main text?

commented

Decisions, decisions ;-)

Good work, as always, and good to keep a record of the discussions, reasons and decisions like this.

Keeping an Eye on Code Ligatures

Yes. Ligatures should definitely be avoided in code sections. When you say "test" I pressume manual ocular inspection? Or is there a way to do this automatically? If so, we could add a Continuous Integration build to this project. I have some others set up with Travis, and as long as we have scripts to do what we want, we can build all docs automatically on every push.

Upcoming Fonts Preview

Looking forward to this, and feel free to "take some liberties".

At this point I have no preferences or suggestions for font combinations. So also, for Sanserif in body text. I happily read Serif fonts too, if moderate "serifed", they are actually easier to read. But we don't want it to look ancient, like Times. So either is ok if the overall aesthetics is good.

commented

When you say "test" I pressume manual ocular inspection? Or is there a way to do this automatically?

Yes, manual checks by looking at the test docs and see if ligatures are present, and sometimes compare to screenshot images therein. I've asked around, but it seems that there is no easy way to look into a fonts internals to check for ligatures. Only specialized font tools are able to do that.

But this is going to be a problem only at font selection time, once the PDF and HTML outputs have been visually checked to behave as expected we're good to go. These are added reasons why I want to include the fonts in the project. The FOP/PDF toolchain doesn't even require the fonts to be installed on the system, providing a path to them is enough, and they'll be embedded in the final PDF.

commented

Just had to do a quick google, how about Ziggurat+Knockout?

More an example of how much good information and knowledge (font pairing) there is out there. But probably you already knew.

commented

Decisions, decisions ;-)

I know that I lean toward the «pedantic» when it comes to confirmations (and I apologise for that), but being myself a bit touchy when it comes to others changing my own stylistic choices I tread carefuly when I find myself in the inverted role.

It's The Cousins' Fault!

I've had terrible experiences when I used to work as a website designer, and realized to my own shock that my original website designs had been «adjusted» (read: vandalized) by the client's cousin — believe it or not, in Italy everyone happens to have a cousin or nephew who's an «expert in computers» (e.g. an «HTML programmer», horribile dictu as it might sound, that's the frequent claim). Needless to say, these experts tend to be cheaper to hire due the family bond, which also grants them a higher degree of freedom in terms of «adjusting» and «retouching» the final product.
Mysterious as it may sound, these «expert cousins» tend to loiter all day long in cafés, driking beer and watching football on the Bar's Tv; maybe their loitering is both a luxury and a sign of their high level of expertise (having reached the peak of the art, they need not bother any longer to engange in any particular activity).

After seeing a of couple of these cousin's adjustments, I had realized that you shouldn't sign a website with your name unless you are in total control of the server account, with exclusive rights to changes. It was painful to see my name associated with despisable color schemes «adjusted» by sad fellows who didn't have a chance to play with color pencils and crayons at kinder garden (an unforgivable shortcoming on the educational system, which produced a generation of chromo-aphasic bulldozers ready to remorslessly stomp on carefully designed color schemes and devastate them).

It's one of Murphy's Laws: No matter how perfect your own work looks to you, there's always going to be one of the client's cousins waiting around the corner, ready to «correct» your work and shine in front his uncle.

Cousins are legion, artists are rare.

Sure, beauty is in the eye of the beholder, and there is personal tastes, and a thing called freedom of expressions, which is all fair and nice — and a futher reason not to fiddle with others' stylistic choices. Still, I'm convinced that there is an underlying proportion regulating beauty, and nature abunds in examples when it comes to the "Divine Proportion" (Golden Mean, Phi) being found everywhere, and especially in the greatest arts. So, some eyes are less trained than others at investigating the measures of beauty. Probably you can count on the tip of your fingers those amongst the «cousins and nephews» who have ever used a Phi ruler in Photoshop, let alone hope they ever read a book on color harmonies, or even color-calibrated their monitor.

Better pushy than sorry! I rather ask before changing, as I surely don't wish to be anyone's cousin. 😉

Hopefully, this brief resume of the devastating professional tragedies (😱) that have befallen me might help you understand my pedantry in asking permission before subverting styles.

Travis CI

If so, we could add a Continuous Integration build to this project. I have some others set up with Travis, and as long as we have scripts to do what we want, we can build all docs automatically on every push.

Fonts issues aside, this could be a good idea in its own right.
I haven't used Travis CI up to now, but I did look into it and it's indeed a good added value to any project.

I should probably start to convert all the current scripts to Bash scripts, because if I remember correctly Travis only works the Linux way. Also, Bash scripts are going to be usable crossplatform, as even on Windows OS any Git users will have installed Bash for Windows together with Git.

I must check how Travis supports all the required dependcies (Asciidoctor, Asciidoctor-fopub, etc.) as some of these are currently being installed separetely from the project — Asciidoctor-fopub might need need looking into it especially, since it has itself many dependencies (Java, Gradle, XSL stylesheet, XSLHL, etc).

commented

Entertaining story!

Travis is fairly easy to set up here is one I have for a C-project. Adding dependencies is also easy, just a sudo apt install ... in your .travis.yml, if I remember correctly. Unless you need to build some of the dependencies...

commented

Just had to do a quick google, how about Ziggurat+Knockout?

I've had a look at them, but since they are both commercial fonts I took them as an example, and went looking for similar types, especially slab serifs.

Fonts searching is always extremely time consuming, especially when you have strict criteria that the fonts need to meet.

Avoiding SIL Open Font, Unless Webkit Is Available

I always try to avoid fonts with the SIL Open Font license, unless they don't come already with webfonts or I can't find similar alternatives with other licenses. The SIL license imposes that if you change anything in the font (even a bit) then you have to rename the font. Online tools won't create webfonts from SIL licensed fonts, for this very reason.

This complicates creating webfonts for the html document, as it forces you to rename the font and readapt the SIL license accordingly. To keep same fonts names in the project, even the TTF/OTF font would have to be renamed, and this can be a troublesome operation and require some font editing tools to access the font file metadata. Same problem applies to font subsetting, as that would be derivative work too.

I can understand the reasons behind this, as it's intended to prevent proliferation of altered (and corrupted) fonts. Derivate works must choose another font name that doesn't contain part of the original name (ie, can't rename a font called "ZipZap" to "ZipZap New" or "Zap II", etc.)

So, I try to find Apache licensed fonts whenever possible, as these provide greater freedom. SIL Open Font and Apache are the most common open source fonts licenses (SIL more so).

Of course, this further narrows down choices.

Roboto Slab + Open Sans

Here's a screenshot of a nice font combination that should be along the lines of the fonts in your link (couldn't find any free fonts quite like Ziggurat though):

Roboto Slab + Open Sans

This is the link to both fonts on Google Fonts:

For some reasons, you can't create a direct link to font combinations previews on Google Fonts, but the above link selects both Roboto Slab and Open Sans with the required styles.

Roboto doesn't have italic style though! I'm not sure if this could be a problem; since that would be the font for headings, probably not, but in same cases italics in headings are required.

So, we might have to look for a similar font that meets the criteria.

Believe me, once you start looking at criteria like extended characters sets, styles and weights, ligatures, availability of webfonts, etc., the list of free fonts becomes incredibly slim.

Fonts (good fonts) have always been expensive, and for a good reasons.

Some open source fonts, like the DejaVu fonts family project (and a few others), are rare excpetions for they have been designed collaboratively to ensure that their font family covers as many languages, Unicode characters and subsets and ligatures as possible, and often provide alternative releases of the same font with slightly different ways to represent some letters (like the zero, with slash or with point inside, etc.).

Behind such projects you'll find teams of experts who worked hard to optimize the vector glyphs, test them across languages, etc., and if it wasn't for international collaboration you wouldn't have all these non-latin languages covered by the font (Arabic, Hebrew, Urdu, etc.), the phonetic alphabet glyphs, and all the math and science symbols which the font covers in a fully compliant way.

Nice fonts and good fonts are too often world aparts.

As for free (non open source) fonts, very often the free version covers only the basic Ascii characters, and it's more like a demo of the commercial version which provides glyphs for special accented characters, or non-latin alphabets. If you take this into account, the number of "free fonts" immdediately shrinks down.

commented

WikiPedia conatins a good page on Unicode compliant open source fonts:

commented

Ciao @thoni56,

I've just update the project to include 3 fonts to build the PDF:

which are now in the _assets/fonts/ folder.

At the end, I just compromised on 3 fonts that were available in all the required sytle and weight variants, and that are also available as webfonts. Finding three fonts that met these criteria wasn't easy, and took me much longer than I wished for.

I know that these might not be the definitive fonts to use in the PDF docs, but I needed to have a base point to work on — i.e. tweak the FOP XSL settings and configuration to allow using custom fonts. (I'll spare you details on the amount of effort it took to make all the documents share the same XSL configuation, due to relative paths problems)

So, I though it was better to setup the project so that it can use custom fonts at all, and if we find better fonts later we just substitute them; for there are still some issues with the PDF format when it comes to special characters.

Anyhow, they are quite good looking fonts, although the headings font is not quite as thick and fancy as the cool slab font you indicated. But finding that sort of font for free, with italics and bold+italic styles too, is really hard. Most fancy heading fonts are usually available in limited style, and italic is rare.

I'm quite happy I've manage to setup using DocBook FOP with custom fonts, as it was not complications free. The fonts don't actually need to be installed on the computer, they only have to be inside the project. If my understanding of the settings is correct, these get embedded in the PDF and even who doesn't have these fonts should be able to see them (I tired using a font which is not in my system, and it showed up correctly in the PDF).