Applying a unified style to the document

[mostafah]

As I was drafting my sections, some style-related questions came to my mind:

• Should we show the characters in images from left to right or from right to left?
• What size should we use for example texts in images, in-image explanations, and the resolution of the images themselves?
• Is it possible to use SVG images?
• How should we refer to other works? By its unique code or its full name?

We don’t have to think about these yet. I did my work without worrying about these questions. But I created this issue to have a place to gather these issues as they come up while we work.

BTW, there might be a W3C style guide that we can use.

[r12a]

i struggled with how to represent rtl and bidi text in examples when writing the educational articles on the w3c site. I think the article at http://www.w3.org/International/articles/inline-bidi-markup/ shows my approach at its most evolved state - see the explanation in the purple box and look at the examples to see whether they look workable.

we're about to move to a new document style that imposes a 50em max width on the main text column, although if needed we should be able to use wider tables and diagrams. That should give you a rule of thumb for the overall size. Any caption text should be in the caption element. It would be good to keep other explanatory text in an image to a minimum. For Arabic text, i recommend a size that is big enough for non-arabic-using people to clearly see what's going on.

it is possible to use SVG (it's used already in the clreq and tlreq docs).

in W3C docs it is common to use [DOCNAME] type links to the references section. I never thought this was very helpful. It springs from academic rather than practical sources. I recommend that links in the document link directly to the document being cited, and to the relevant place inside that document. We can also use the [DOCNAME] links to provide information about the name of the document, if useful.

here's a style guide that you may find useful http://www.w3.org/International/docs/styleguide. See also the respec guidelines (esp. for things like linking to definitions, figures, etc.) https://www.w3.org/respec/ref.html

hope that helps

[r12a]

See also the editorial guidelines at https://github.com/w3c/alreq

[mostafah]

:+1:

[mostafah]

Thanks for the links and explanations.

I want to add another note for when we want to review the style of the document and that is unifying typefaces we use in the images (unless, of course, a specific typeface is needed for an image).

[shervinafshar]

I recommend listing your preferred fonts here so others can comment on the matter as well.

We can use this issue as a catch-all for all style-related discussions and in the end hope that we can have a set of guidelines extracted from the discussions which can be amended to existing W3C style guide recommendations.

[mostafah]

That’s exactly what I’m using this issue for. Right now, I’m more interested in recording the questions, rather than discussing their answers or applying them while drafting, but this discussion is a good place for that too.

I’ve used Mitra, just because it’s kind of a default font for me. In general, if the typeface has to be publicly available for free (and on an English-language website), so that others wan work on this document, that limits the options to a few. These free ones come to my mind:

• Scheherazade
• Lateef
• Amiri by @khaledhosny
• Noto Naskh Arabic

IMO, all of these can work and the first three look great. I personally like Scheherazade.

[mostafah]

I’m not sure, but I don’t guess so. Noto has a Nastaliq Urdu version, though.

[mostafah]

For English, like for in-image descriptions, a lot more options are available. I’ve used Source Sans Pro in my two drafts and I like it.

[khaledhosny]

I think both Scheherazade and Lateef are too simplified to use (Lateef has its own design quirks as well). Obviously I’d choose Amiri, it is a more classical design with rich forms, but others find it too complex. Noto Naskh Arabic is fine, but it suffers from too much simplified forms as well.

[ntounsi]

I have the same preference or both fonts. I usually use Traditional Arabic, but find it unbalanced when mixed with Latin. Amiri is more rich in it's design and make use of ligatures. It better shows the Arabic writing styles.

[mostafah]

A few more points that came up for me while sending our first drafting PR:

• I’ve used red and black in my images. This can be reconsidered.
• Do we need to put letter names in quotation marks?
• My images were a little bit too big, and instead of resizing them I added width="100%" to my img tags.
• Can we update local.css? I wanted to add a style for strikethrough to use for parts of the topic keywords that we’ve covered.

[r12a]

for Unicode character names, i suggest that we use parentheses around the character that follows a Unicode name. Whatever we do in that respect, however, i think we need to wrap the character in <span lang="ar" dir="rtl">...</span>

[you may find it quicker to use http://r12a.github.io/pickers/arabic/ to generate the markup. Just put the character(s) in the big box and click on charLink. It will output something like <a href="/scripts/arabic/block#char0644"><span class="uname">U+0644 ARABIC LETTER LAM</span> (<span lang="ar" dir="rtl">&#x0644;</span>)</a> for you to copy/paste into the document. The link can be easily stripped off - or i could fix the app to not produce it, if preferred.]

[r12a]

for image size, i would suggest 90%, since i felt slightly uncomfortable looking at them with the width at 100%.

wrt the style change, we have local.css set up for you to use del in these situations, rather than strike. Would that work?

great job, btw, to get the first 'real' content in the document!

[mostafah]

Thank you, Richard.

Didn’t notice the del there. Changed image sizes and Unicode character names too.

But I also want to elaborate on my question: “Do we need to put letter names in quotation marks?” It’s about when we mention the name of a letter in text, not a Unicode character. Like this:

… when letters “lam” and “alef” are joined.

[r12a]

it seems a little much to always put quotations marks around letter names. What we could do is put a span around them, which gives us the flexibility to style as we wish (including with quote marks, if desired). How about <span class="lettername">...</span>? My preference would be to italicise the contents of the span.

btw, for the quoted words in [beside the “isolated” form, there are “initial”, “medial”, and “final” forms.] you could, if you like, use <span class="qterm">, which is already defined in local.css to put quote marks around the word. (We may want to change th styling from ' to ‘ and ’.)

[mostafah]

That <span class="lettername">…</span> makes sense. I already did that and added it to my PR.

I’m not very sure about using <span> instead of actual quotation marks. I assume those quotation marks are part of the text and it makes more sense to have them in the actual text, rather than moving them to a presentation layer. On the other hand, I see the advantages of using <span> here, so I’m eager to hearing what you and others have to say about this.

[r12a]

I’m not very sure about using <span> instead of actual quotation marks

i often wondered about this, too, but am thinking recently that it's better to supply the quotes with CSS because it gives greater typographic control and because it makes localization easier. An example of typographic control would be to add small spaces between German quotations marks and the text quoted, or indeed to change the quotation marks in use (say for example you want to follow the typical British model rather than the US model, or vice versa – it's easy to change throughout). This ability to change all quotation marks is also useful when localising, of course, especially if there is also markup around the text. It avoids lots of fiddling and potentially incorrect nesting of quotation marks by the translator.

[mostafah]

@r12a I did that and sent the PR #26 for it. And I changed straight quotes to curly ones in the CSS in the same PR. Do you agree with that change?

[mostafah]

Two notes regarding images in our last meeting:

• We should avoid using texts in images (like “Normal”, … in the following image) to make it easier to change them in the future. We can use texts in SVGs as long as theey are stored as text (not converted to outline) and their font is being embedded in the page.
• It’s better to split a big image like the one below into three smaller images to be able to rearrange them for different screen sizes. (For example, stack them vertically on mobile.)

[mostafah]

Related: #103 (how to expose external links)

[behnam]

Regarding styling of phrases and terms, right now, we have <strong> and <em> tags, as well as qterm and uname classes, but, as far as I understand, their usage is kind of inconsistent throughout the document. Have we reached an agreement about this before?

Here are cases that, IMO, we need to have a fixed markup/style:

• Defining new phrases, specially need to mark them in a way to be linkable, and possibly auto-indexable. We use a mxi of <strong>, <em> and qterm for this right now, I think.
• Referring to already-defined terms, and possibly link to the definition (but not with a big external-link look-n-feel). We use a mxi of <em> and qterm for this right now, I think.
• Unicode character names (which already has uname class).

Any other case we need to define?

And, should we keep <strong> and <em> only for in-text "strong" and "emphasis" usages?

[r12a]

For new terms and linking back to them, please use dfn per the respec guidelines at https://github.com/w3c/respec/wiki/User's-Guide#definitions-and-linking.

Qchar use is explained at http://w3c.github.io/i18n-activity/guidelines/editing#inline – it's basically for putting quotation marks around words, and is unlikely to be used often. Please use uname for unicode character names and their codepoint values (see the previous link). There are other standard inline class names defined there that may be useful, and are already styled in the css style sheet we use.

Please do keep strong and em for their true semantic uses only.

[behnam]

Okay, I'm doing a through clean up on the formatting of the document, so we can maintain a better formatting going forward.

I'll land the fixes in small patches directly on the main repo, as they are not expected to have any content/semantic changes. Please let me know if you think it should be done differently.

And, another question: Why do we start section IDs with h_?

I think we better not do so, as they are the most visible IDs in the document and we would have a cleaner URL with simpler IDs.

Looks like ReSpec manual suggests to keep them simple, too: https://github.com/w3c/respec/wiki/section

If there are no objections, I'll update all the section IDs, in a separate patch, as well.

[r12a]

And, another question: Why do we start section IDs with |h_|?

Because when i added ids at some point (can't remember whether in this doc or another) i found i was introducing clashes with other ids in the document that referred to similar topics. Adding the h_ makes it clear that were dealing with a h_eading, and usually removes the ambiguity.

We don't have to have it, but we need to be more vigilant, if not, that we don't duplicate ids.

Btw, we do have a rule that ids for elements should normally start with dfn_. This is for similar reasons, but tends to be particularly useful because when referring back to that definition from elsewhere, it's clear that the link is pointing to a definition.

I think we better not do so, as they are the most visible IDs in the document and we would have a cleaner URL with simpler IDs.

Looks like ReSpec manual suggests to keep them simple, too: https://github.com/w3c/respec/wiki/section

Respec documentation also suggests using h2 everywhere, which i think is a VERY BAD idea. It's convenient only if you're hand writing the code. Try to edit that code in a wysiwyg editor, or view the file without respec code being available (eg. on a plane) and you lose the hierarchy of the page headings. Bad idea.

[mostafah]

Since now we have #105 for styling images, I reviewed this issue to see if we still need to keep it. Except for the last four comments by Behnam and Richard about tagging and linking terms and phrases, most of the discussion in this issue involved images. So, if having two similar issues is confusing, we can close this one.