Peda penerang kena Templat:Script/Arabic/doc

{{Documentation subpage}}
{{High-use}}
{{Uses TemplateStyles|Template:Script/styles arabic.css}}
<div style="float:right">__TOC__</div>__NOTOC__

This template is to render properly Arabic-based scripts which don't use the main Arabic alphabet, also to ensure that [[Arabic diacritics]] appear properly.

It is also used for the [[Templat:Arabic alphabet shapes]].

== Usage ==
: <nowiki>{{Script/Arabic|موسوعة}}</nowiki> to give you {{Script/Arabic|موسوعة}}
* The 1st parameter is mandatory and contains the text written in the Arabic script.
* The optional <code>style</code> parameter can be used to override the generated style (for example another font size) or to specify additional CSS formattings (e.g. color).
* The optional <code>attributes</code> parameter can be used for specifying additional HTML attributes (for example a descriptive <code>title="..."</code>).

Use simple <nowiki>{{lang|ar|...}}</nowiki> for inline citation of Arabic language. Use {{tl|rtl-para}} for entire paragraphs of Arabic text, however, they do not force choosing the fonts in that template.

== Implementation ==
The template contains this phrase:

<syntaxhighlight lang="wikitext"><templatestyles src="Script/styles_arabic.css" /><span class="script-arabic script-Arab" {{#if:{{{lang|}}}|lang="{{{lang}}}"}} {{#ifeq: {{{no_rtl_mark|+}}} | {{{no_rtl_mark|-}}}||dir="rtl"}} style="font-size: {{{size|125%}}}; {{{style|}}}" {{{attributes|}}}>{{{1}}}</span>{{#ifeq: {{{no_rtl_mark|+}}} | {{{no_rtl_mark|-}}}||&lrm;}}</syntaxhighlight>

* The font size was fixed at 125% for better readability.
* The style <code>font-weight: normal</code> is provided by [[Templat:Script/styles arabic.css]] and present to remove boldness, e.g. in section titles, because Arabic diacritics are best read only in normal weight, but also because some fonts do not exist in bold styles; without it, other fallback fonts would be used instead (possibly with lover coverage), or boldness may be synthetized from a non-bold font (making most diacritics unreadable).
* Specifying the HTML attribute <code>dir="rtl"</code> in a <code>span</code> HTML element is sufficient to also activate on Wikipedia the <code>unicode-bidi: embed</code> style which is part of the site-wide CSS stylesheet; this HTML attribute also activates the CSS style "direction: rtl" (which should be implemented by default in browsers, but is also set in the site-wide CSS stylesheet). This attribute can be disabled via {{para|no_rtl_mark}} with value <code>+</code> or <code>-</code> if necessary.

=== Fonts information ===
;Free fonts:
Template intended to force following fonts if installed:
*[http://software.sil.org/scheherazade Scheherazade New] or [https://software.sil.org/scheherazade/download/previous-versions/ Scheherazade]
*[http://software.sil.org/lateef Lateef] <small>(lacks a bold weight)</small>
*[http://www.amirifont.org/ Amiri] <small>(appears feathery on Windows; errors with combining shadda with kasra and some Rohingya diacritics [https://github.com/alif-type/amiri/issues/155])</small>
*[https://fonts.google.com/noto/specimen/Noto+Naskh+Arabic Noto Naskh Arabic]
*[https://fontlibrary.org/en/font/droid-arabic-naskh Droid Arabic Naskh] <small>(better at smaller sizes; has an error in displaying</small> [[Riyal|<span dir="rtl" style="font-family:'Noto Naskh Arabic',KacstOne,'DejaVu Sans','DejaVu Sans Condensed',Harmattan,'Iranian Sans',Scheherazade,Lateef,'Arabic Transparent'; font-size:125%">ريال</span>]]<small>)</small>
*[https://fonts.google.com/noto/specimen/Noto+Sans+Arabic Noto Sans Arabic]
*[http://software.sil.org/harmattan Harmattan] <small>(lacks a bold weight; errors with combining shadda with kasra)</small>

These fonts contain all Arabic character defined in Unicode (see [[Arabic script in Unicode]]) for text in the various languages that use the [[Arabic script]], but not all the redundant glyphs used in stylizing.

;Non-free fonts:
If the previous fonts are not installed, other fallback fonts would display:
* SF Arabic <small>(is a complete ''[[Apple OS|Apple]]'' font)</small>
* [[Core fonts for the Web#External links|Arial]], Times New Roman <small>(essentially look the same; lack a few characters; errors with combining shadda with kasra)</small> Arabic Transparent
* Caribri <small>(only the newer versions render Arabic)</small>
* Microsoft Sans Serif <small>(lacks a few characters; lacks a bold weight; errors with combining shadda with kasra)</small>
* Segoe UI <small>(lacks a few characters; errors with combining shadda with kasra; in older versions, lacked a normal weight)</small>
* Sakkal Majalla <small>(errors with combining shadda with kasra)</small>
* Microsoft Uighur <small>(lacks a few characters; has errors with combining shadda with kasra; lacked a bold weight on older versions)</small>
* Arabic Typesetting <small>(lacks a bold weight; errors with combining shadda with kasra)</small>

== How to override fonts in user's preferences ==
Any user can use another font with a different size by writing the following on [[Spesyel:Mypage/vector.css|his custom CSS]]. (see [[Bantu:User style]])

An example making the font size 105%, and choosing Droid Arabic Naskh to be the main font with Arial as an additional font :
<syntaxhighlight lang="css">
.script-arabic {
    font-size: 105% !important;
    font-family: 'Droid Arabic Naskh', Arial, sans-serif !important;
}
</syntaxhighlight>
: Font names containing spaces (or any other character than a letter) need to be put between <code><strong>'</strong></code> or <code><strong>"</strong></code>.
: The list of fonts should always be terminated by the pseudo-font names "sans-serif" and/or "serif", to allow using the fonts defined in user preferences in their browser, or the fonts set by default in browsers.
: You may choose to add the line-height phrase if you wanted to make lines in a paragraph more spaced from each other, or less spaced. <code>line-height: 125%;</code> Remember to put it before the }. The more number percentage, the more space is added. If you wanted to decrease the line height spacing, decrease the percentage. You may use any number (e.g. 85% or 140%) or use the special value "normal" which will properly use the minimum setting of the line-height recommended by each candidate font. 
: Some Arabic-based letters aren't rendered properly by some old versions of ''[[Times New Roman]]'', such as: {{raise|0.6em|2=<span dir="rtl" style="font-family:'Noto Naskh Arabic', 'Droid Arabic Naskh', Harmattan, Scheherazade, 'Scheherazade New', Lateef, 'Microsoft Uighur', 'Arabic Typesetting', 'Sakkal Majalla', 'Segoe UI', 'Microsoft Sans Serif', Arial; font-size: 200%; line-height:1.6;">ېـ&nbsp;ـېـ&nbsp;ـې&nbsp;ې</span>}} which is used in [[Pashto language|Pashto]] and [[Uyghur language|Uyghur]]; the newest versions of the following fonts render it properly: '''''Scheherazade New, Scheherazade, Lateef, Amiri, Noto Naskh Arabic, Droid Arabic Naskh, Noto Sans Arabic, Harmattan,''''' Arial, 'Times&nbsp;New&nbsp;Roman', 'Sakkal&nbsp;Majalla', 'Microsoft&nbsp;Uighur', 'Arabic&nbsp;Typesetting', 'Microsoft&nbsp;Sans&nbsp;Serif', 'Segoe&nbsp;UI'. (The newest versions which are available free-of-charge online are marked as '''bold'''.)
* A demonstration with ''[http://software.sil.org/scheherazade Scheherazade New]'' or ''[https://software.sil.org/scheherazade/download/previous-versions/ Scheherazade]'' added first at 175%: <span dir="rtl" style="font-family: 'Scheherazade New', Scheherazade, Lateef, 'Microsoft Uighur', 'Arabic Typesetting', 'Sakkal Majalla', Arial, 'Arabic Transparent', 'Times New Roman', 'Noto Naskh Arabic', Harmattan; font-size: 175%">موسوعة</span> &nbsp; That font is freely available online, but if you chose to use it, you must increase the text size, because it shows it very small compared to other fonts.
* A demonstration with ''[https://fontlibrary.org/en/font/droid-arabic-naskh 'Droid Arabic Naskh']'' added first at 105%: <span dir="rtl" style="font-family: 'Droid Arabic Naskh', Arial, 'Arabic Transparent', 'Times New Roman', Harmattan; font-size: 105%">موسوعة</span> &nbsp; However, it has an error in displaying the word (<span style="font-size:125%; font-family:'Noto Naskh Arabic', 'KacstOne', 'DejaVu Sans', 'DejaVu Sans Condensed', Harmattan, 'Iranian Sans', Tahoma;margin-right:2px;margin-left:1px">[[riyal|ريال]]</span>), it is folded on itself, rather than normally rendered in ''[[naskh (script)|naskh]]''.
* A demonstration with ''[https://fonts.google.com/noto/specimen/Noto+Naskh+Arabic Noto Naskh Arabic]'' added first at 125%: <span dir="rtl" style="font-family: 'Noto Naskh Arabic', Harmattan, Scheherazade, 'Scheherazade New', Lateef, 'Microsoft Uighur', 'Arabic Typesetting', 'Sakkal Majalla', Arial, 'Arabic Transparent', 'Times New Roman'; font-size: 125%">موسوعة</span> &nbsp; That font is freely available online.
* A demonstration with ''[http://software.sil.org/harmattan Harmattan]'' added first at 125%: <span dir="rtl" style="font-family: Harmattan, Scheherazade, 'Scheherazade New', Lateef, 'Microsoft Uighur', 'Arabic Typesetting', 'Sakkal Majalla', Arial, 'Arabic Transparent', 'Times New Roman'; font-size: 125%">موسوعة</span> &nbsp; That font is freely available online.

Example:
<syntaxhighlight lang="css">
.script-arabic {
    font-size: 125% !important;
    /*
       The default line-height used by Wikipedia is 1.5 em, which can be lower or higher than the font default,
       reduce it to the minimum recommended for HTML by using the word normal or for example, use a percentage
       value, as 95%
    */
    line-height: 95%;
    font-family:
        /* The following fonts are recommended for best coverage of the Arabic script: */
        'Noto Naskh Arabic', Scheherazade, 'Scheherazade New', Lateef, 'Droid Arabic Naskh', Harmattan     /* free fonts */
        'Sakkal Majalla',                         /* commercial font, also installed with recent versions of Windows */
        'Microsoft Uighur', 'Arabic Typesetting', /* commercial fonts installed with recent versions of Windows */
        /* Other fonts supporting the Arabic script with partial coverage: */
        Arial,                /* Warning! Old versions may not support a few characters. */
        'Times New Roman',    /* Warning! Old versions may not support a few characters. */
        /* Default fallback fonts determined in the browser: */
        sans-serif /* No comma here! */
        /* Required at end to actually enable the override and make it work : */
        !important;
}
</syntaxhighlight>

<br/>
Another example without the notes:
<syntaxhighlight lang="css">
.script-arabic {
    font-size: 125% !important;
    line-height: 95%;
    font-family: 'Noto Naskh Arabic', Scheherazade, 'Scheherazade New', Lateef, 'Droid Arabic Naskh', Harmattan,
    Arial, 'Times New Roman', 'Sakkal Majalla', 'Microsoft Uighur', 'Arabic Typesetting', sans-serif !important;
}
</syntaxhighlight>

==Template Data==
{{Template data header}}
{{cot|title=Parameter list|bg=#CCC}}
<templatedata>
{
	"params": {
		"1": {},
		"no_rtl_mark": {},
		"size": {},
		"style": {},
		"attributes": {}
	},
	"paramOrder": [
		"1",
		"no_rtl_mark",
		"size",
		"style",
		"attributes"
	]
}
</templatedata>

{{cob}}

== See also ==
* [[Templat:Arabic alphabet shapes]] (its documentation page features a table showing a full test of contextual Arabic letter shapes supported).
* [[Templat:Ug-textonly]] (enable Uyghur styled fonts)
* [[Templat:Script/Nastaliq]] (used for the text written in Nastaliq styled Arabic script)

<includeonly>{{Sandbox other||
<!-- Categories go here: -->
[[Kategori:Script–font templates]]
}}</includeonly>