/info/doc/guide.md

نسخة
----

تستطيع أن تحصل على نسخة من خلال [موقع المشروع التطويري]. إصدارات المشروع تحمل رقم 
الإصدار ضمن اسم الملف، فإسم ملف [الإصدار الأول] للمشروع هو
    
        armath.ver1.js

بينما تتغير `ver1` إلى `ver2` للإصدار الثاني، وهكذا.

[لموقع المشروع التطويري]:https://bitbucket.org/seininn/armath.js/downloads
[الإصدار الأول]:https://bitbucket.org/seininn/armath.js/downloads/armath.ver1.js


إضافة المجمع إلى موقعك
----------------------

يمكنك أستخدام المجمع مباشرة بمجرد إضافته إلى صفحة HTML، وذلك من خلال **معلم** `script` 
المعتاد. لصفحات الـHTML5:

        <script type="text/javascript" src="armath.ver1.js" >

غيّر `ver1` إلى الإصدار المستخدم. 

للمجمع طريقتين في ترجمة العبارات الرياضية في صفحات الـHTML. أولى الطريتين هي 
ترجمة محتوى جميع المعلمات المصنفة بـ`armath-eq` في الصفحة بغض النظر عن نوعها، مثل:

        <div class="armath-eq"> 
         1 = 1\2 + 1\4 + 1\8 + 1\16 + ...
        </div>

وذلك من خلال تنفيذ الدالة `armath_render`. (يمكنك وضعها في `onload` المعلم `body`)

الطريقة الثانية هي ان تمرر سلسلة محارف إلى الدالة `armath_render_string`، التي 
تترجم السلسلة إلى HTML، ثم ترجعها على هيئة سلسلة HTML.

فيما يلي روابط لأمثلة للطريقتين -إطلع على مصدر الصفحتين:

* [الطريقة الأولى]
* [الطريقة الثانية]

[الطريقة الأولى]:examples/armath_render.html
[الطريقة الثانية]:examples/armath_render_string.html


تغيير الإعدادات الافتراضية
------------------------

يمكنك تغيير ببعض جوانب عمل المجمع من خلال تغيير قيم متغيرات معينة، وذلك من خلال
وضع `true` أو `false` بالمتغيّر كما في السطر التالي (والذي يؤثر على رسم الأرقام
كما سيتقدم):

        var armath_translate_numrals = false;
        
فيما يلي أسماء المتغييرات والجوانب التي تأثر عليها:

* المتغير `armath_translate_numrals` يحدد إذا ما كانت الأرقام العربية الغربية تترجم 
  لنظيراتها الشرقية. `true` لسماح بالترجمة بينما `false` تمنعها. القيمة الإفتراضية 
  هي `true`.



وصف العبارات الرياضية
---------------------

وصف العبارة الرياضية هو سلسلة الحروف والرموز التي يستقبلها المجمع ويترجمها إلى 
معادلات. تنقسم مكونات الوصف ثلاثة أنواع:

    1. إختصارات
    2. بيانات
    3. شواذ

[الاختصارات] هي كلمات أو رموز معينة لها آثار خاصة، ويمكنها التأثير على ما يليها 
وما يسبقها، وقد لا يتعدى أثرها نفسها. الإختصارات تسبق بالرمز `$` إن كانت كلمات.

قد يكون للأختصارات **مدخلات**، وأن كان كذلك، فإنها تكون إلزامية ولا يمكن 
تركها. تحدد المدخلات بإحاطتها بأقواس  وإلصاقها بلإختصار نفسه. أمثله على ذلك:

        $جذر(2)(9) = 3
        
<div class="armath-eq" style="width:88%;text-align:center;margin-left:20px;margin-right:20px;border:1px dashed black"> $جذر(2)(9) = 3 </div>

        $جذر()(4) = 2
        
<div class="armath-eq" style="width:88%;text-align:center;margin-left:20px;margin-right:20px;border:1px dashed black"> $جذر()(4) = 2 </div>
        
        $ضخم( $لامدا )
        
<div class="armath-eq" style="width:88%;text-align:center;margin-left:20px;margin-right:20px;border:1px dashed black"> $ضخم( $لامدا ) </div>

        $لانهاية
        
<div class="armath-eq" style="width:88%;text-align:center;margin-left:20px;margin-right:20px;border:1px dashed black"> $لانهاية </div>

قد يلي الإختصار مدخلاته في بعض الحالات:

        (1)\(0) = $لانهاية
        
<div class="armath-eq" style="width:88%;text-align:center;margin-left:20px;margin-right:20px;border:1px dashed black"> (1)\(0) = $لانهاية </div>
        
وقد يكون للعملية الواحدة عدة إختصارات:

        $كسر(1)(0) = $لانهاية
        
<div class="armath-eq" style="width:88%;text-align:center;margin-left:20px;margin-right:20px;border:1px dashed black"> $كسر(1)(0) = $لانهاية </div>
        

يمكنك أن تطلع على كافة الإختصارات وعدد مدخلاتها في [صفحة الاختصارات].

أما البيانات، فهي بدورها تنقسم إلى قسمين: بيانات مترابطة وغير مترابطة. أما البيانات 
المترابطة تتألف من الحروف العربية و الأرقام و الرمزين `.` و `,`، وأما البيانات الغير
مترابطة، فهي تشمل ما دون ذلك.

للبيانات المترابطة خاصية جديرة بالذكر، ألا وهي أمكانية إهمال أقواس الإختصارات معها.

        1\2 + 1\4 = 0,75

<div class="armath-eq" style="width:88%;text-align:center;margin-left:20px;margin-right:20px;border:1px dashed black"> 1\2 + 1\4 = 0,75 </div>

الشوذ عبارة عن "إختصارات" غير خاضعة لقوانين وقيود الإختصارات الطبيعية. أهم هذه الشواذ هي إختصار المصفوفات الذي يتكرر فيه رمزه في صف\سطر وصيغتها هي:

        #(أ)(ب)(ج)
        #(د)(هـ)(و)
        #(ز)(ح)(ط)

<div class="armath-eq" style="width:88%;text-align:center;margin-left:20px;margin-right:20px;border:1px dashed black">#(أ)(ب)(ج)#(د)(هـ)(و)#(ز)(ح)(ط)</div>

ملاحظة:

* لا مانع من كتابة سطور المصفوفة على سطر واحد: `#(أ)(ب)(ج)#(د)(هـ)(و)#(ز)(ح)(ط)`.
* يمكنك إستخدام الإختصار الشاذ `¦` (وليس |) لوصف المتجه الرأسي بدلا من إختصار المصفوفة.

هناك ثلاثة أنواع من الأقواس "البدائية" التي يوفرها المجمع. الأقواس الهلالية، والأقواس المربعة، والمطلق. وتكتب هذه الأقواس في وصف العبارة كما تكتب في أي مكان آخر.

        (1\3) 

<div class="armath-eq" style="width:88%;text-align:center;margin-left:20px;margin-right:20px;border:1px dashed black">(1\3)</div>

        [ #(أ)(ب)(ج)
          #(د)(هـ)(و)
          #(ز)(ح)(ط) ]

<div class="armath-eq" style="width:88%;text-align:center;margin-left:20px;margin-right:20px;border:1px dashed black">[#(أ)(ب)(ج)#(د)(هـ)(و)#(ز)(ح)(ط)]</div>

وأختم بأن أسرع طريقة لتعلم كتابة العبارات الرياضية هي النظر إلى الأمثلة في [صفحة النماذج] وإلى [صفحة الاختصارات]، وقرأة فقرة 
**صيغة وصف العبارات الرياضية** التالية.

[صفحة النماذج]:test.html
[صفحة الاختصارات]:reference.html
[الاختصارات]:reference.html







صيغة وصف العبارات الرياضية
--------------------------

طريقة وصف العبارات هي نفسها التي تستخدم في وصف العبارات في الآلات الحاسبة مع
الإختلافات التالية:

* دور الفراغات الرأسية والأفقية (بشكل عام) هو فصل أجزاء الوصف عن بعضها بعض، 
والفراغ الواحد مثل مجموعة الفراغات المتتالية إذ لا فرق بينهما بنسبة للمجمع.
لهذا يمكنك إستخدام الفراغات كيف ما شئت شريطة ألا تستخدم إلا في مواضع التي 
يمكنك استخدامها فيها. مثال:

        س + 1 = 0  يكافئ   س+1=0  ويكافئ   س
                                          +1
                                           =
                                           0
                                          
    
* أركان العبارة إما حروف عربية، أو أرقام (هندية أكانت او عربية).
* الحروف العربية المتتالية او الأرقام المتتالية تأخذ على انها شيء واحدة،
بينما أي رمز آخر يؤخذ منفصل بمفرده بغض النظر عن ما إذا تبعه رمز مشابه.
* تُسبق الإختصارات بإشارة $ إذا كانت تكتب بحروف عربية.
* تستقبل الإختصارات المدخلات، إن استلزمتها، وهي **محاطة بالأقواس**، ويمكن 
إهمال الأقواس إن كانت المدخلات حروف عربية او أرقام فقط وتجب الأقواس لما دون 
ذلك.
        

        $كسر(5)(س^2)                5
                                 -------
                                    س²

* **لا يمكن إضافة الفراغات بين المدخلات. لأن الفراغ علامة إنتهاء مدخلات الإختصار.**

        $جذر(3) (8)     استخدام خاطئة
        $جذر(3)(8)      إستخدام صحيح

    

* يجب أن يتوافق عدد المدخلات مع عدد الذي يتوقعه الأختصار، ولا يمكن ترك مدخل وإن 
لم يكن مستخدما (يسمح بتمرير أقواس فارغة لتحل مكان المُدخل الناقص). عدد المدخلات
مبين في [صفحة الاختصارات].
        
        $جذر(س)         استخدام خاطئة
        $جذر()(س)       إستخدام صحيح

* قد يكون الإختصار مثل `^` رمز وليس كلمة كـ`جذر`.

        ()^()       الرمز ^ هو اختصار للأس

* قد يكون للاختصار اختصار آخر مكافئ له.

        $كسر()()    مكافئ لـ    ()\()     لاحظ ان المدخل الأول *سبق* الإختصار

* بعض الاختصارات تأخذ ما يسبقها اول مدخل لها. الاختصارات التي تعمل بهذه الطريقة معلمة
بـ"نعم" في خانة "يتبع مدخله الأول" في [صفحة الاختصارات].
        
        (1)\(2)

* لا مانع من عدم إحاطة المدخلات بالأقواس إذا كانت ارقاما او حروف عربية، وتلزم الأقواس 
لما دون ذلك.

        1\3             استخدام صحيح
        كتلة\الحجم       استخدام صحيح
        v\m             استخدام خاطئة
        (v)\(m)         استخدام صحيح 
        


طلب
---
المشروع ما زال في طوره الأول، وفي حاج ماسة إلى التعديلات. لهذا إرسال تقرير عن أي 
خطأ تصادفه حتى أستطيع تحسينه.


للاتصال
------

يمكنك الإتصال بي من خلال [صفحة الإتصال] الخاصة بي او بفتح [ملف تحسين جديد] لدى موقع 
المشروع التطويري. يمكنك أيضا ترك رسالة في [منطقة الحوارات] الخاصة بهذا المشروع.

[صفحة الإتصال]:http://people.sigh.asia/~sulaiman/contact
[ملف تحسين جديد]:https://bitbucket.org/seininn/armath.js/issues/new
[منطقة الحوارات]:http://127.0.0.1:8000/discuss.html


ملحق أ - مصطلحات
----------------

* **أرمث**        إسم هذا المشروع والمجمع البرمجي الناتج عنه.
* **اختصارات**    كلمات أو رموز تدل على عملية أو رمز رياضية. مثال: $كسر $مجموع $لامدا
* **مدخلات**       معلومات إضافية التي يستلزمها الاختصار. مثل العدد 1 و 2 في "$كسر(1)(2)"
* **وصف**         سلسلة الحروف والرموز التي يستقبلها أرمث ويترجمها إلى معادلات
* **معلم**        Tags