كيفية تنسيق رمز المصدر في وثيقة Framemaker؟ [مغلق

Question

لا بد لي من كتابة وثيقة فنية في Framemaker تشرح العديد من رمز مصدر البرمجة.

لذلك يتكون مستندتي من مجموعة من النص ، تليها مجموعة من التعليمات البرمجية المصدر (Java ، XML) ثم يليها المزيد من النص ، إلخ.

هذا السؤال لا يتعلق بما إذا كان ينبغي علي أو لا ينبغي أن أستخدم Framemaker - وهذا هو البرنامج الذي يجب أن أستخدمه. . .

ما أنا في حيرة من أمري هو كيفية تنسيق رمز المصدر كجزء من المستند الخاص بي. هل قام أي شخص بذلك لمستند فني وتصادف أي تعليمات أو نصائح؟ حتى الآن لم ينتج غوغلينغ أي شيء ذي صلة بما يجب علي فعله.

Answer 1

على الأقل ، قم بإنشاء نمط فقرة لعينات التعليمات البرمجية ، واستخدم خطًا جيدًا جيدًا ، ولا تنس إيقاف تشغيل الواصلة.

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

Answer 2

من ورقة كتبت على هذا منذ بضع سنوات والتي ستكون متاحة مرة أخرى عبر الإنترنت الأسبوع المقبل.

يهتم المصممون في المقام الأول بالوضوح ، ولديهم أدوات وممارسات وتقاليد يعود تاريخها إلى مئات ، وفي الواقع آلاف السنين التي تعتمد عليها عند وضع النصوص في اللغات الطبيعية. ومع ذلك ، لا تتم كتابة برامج الكمبيوتر باللغات الطبيعية. وهي مكتوبة في "لغات البرمجة": اللغات الاصطناعية ، التي لها قواعد بناء الجملة الخاصة بهم ، واتفاقياتها الخاصة للعرض ، ومعاييرها الخاصة للوائح. وبالتالي فإن رمز الكمبيوتر هو مجال خاص للتنضيد ، تمامًا كما هو الحال مع الموسيقى والرياضيات والكيمياء. هذه المجالات لها قواعدها الخاصة ، والتي ليست القواعد المستخدمة عند تحديد اللغات الطبيعية.

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

1. استخدم خط Sans serif. في أحد كتبي ، استخدمت نفس عائلة الخط ، FF Scala للنص و FF Scala Sans للرمز. أعتقد أن الأمر يبدو رائعًا ولكن هناك آراء مخالفة: قد تجبرك على استخدام خط أحادي ، على الرغم من أنني شخصياً أعتقد أن هذا قديم جدًا. تجنب البريد السريع ، لا تمتزج مع أي شيء.

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

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

4. فواصل الخط هي جزء من التدوين. لا تضيف فواصل الخط دون استشارة المؤلف.

5. علامات الاقتباس هي جزء من التدوين. لا تتغير إلى مضاعفة أو العكس.

6. التبرير: تتم دائمًا كتابة برامج الكمبيوتر ومشاهدتها وتعيينها إلى اليسار المليئة باليمين.

7. فواصل الصفحة. عند تعيين رمز الكمبيوتر في كتاب ، لا يمكن لفواصل الصفحات فقط اتباع مبادئ اليتيم/الأرملة البسيطة المستخدمة عند إنشاء اللغات الطبيعية. بدلاً من ذلك ، يجب الاحتفاظ بـ "الكتل" المنطقية للرمز معًا إذا أمكن. لا يمكن عادةً أن يحدد المصمم المطبعية حدود الكتلة في التعليمات البرمجية ، على الرغم من أن الخط الفارغ يكون عمومًا نقطة مقبولة لكسر الصفحة. يجب الاحتفاظ بـ "تعليقات الحظر" مع كتلة التعليمات البرمجية التالية. إذا كنت لا تعرف ما هي هذه ، اسأل المؤلف.

8. الواصلة. لغات البرمجة ليست لغات طبيعية ولا تلاحظ اتفاقيات الواصلة المعتادة. استشر المؤلف إذا كنت بحاجة إلى الواصلة ، أو لا تفعل ذلك. يجب ألا تكون النص في نص البرنامج غير متصلب أو مكسور الخط إلا وفقًا لتعليمات المؤلف.

9. احرف كبيرة وصغيرة. عادة ما تكون الحالة في رمز البرنامج مهمة للكمبيوتر ، وعمليًا دائمًا للكتاب وقراءهم. غالبًا ما يتم استخدام أزواج من الكلمات التي تختلف فقط في الحالة ، والتي تمثل أشياء مختلفة: مثل BufferedOutputStream و BufferEdoutputStream. عادةً ما يكون المبرمجون ، وخاصة مؤلفي البرامج ، منهجية للغاية حول الحالة ، بطرق قد لا تكون منطقية بالضرورة للمطبع (أو المبرمجين الآخرين!).

توصيات عملية

• المسافة البادئة في وحدات EM. الحل للعديد من المشكلات في برامج الكمبيوتر هو EM. من المرجح أن تكون علامات تبويب المؤلف إلى المضاعف التالي من 8 مسافات (1 ، 9 ، 17 ، ...) ؛ يجب أن تكون علامات التبويب المطبعية لرمز البرنامج في مضاعفات 1 أو 2 EMS. قد يكون تبني EM كوحدة المسافة البادئة في البداية "مضحكة" للمؤلف ، لأن الباثقين قد يكونون أضيق بكثير من شاشات الشاشات أو المطبوعات. ومع ذلك ، طالما تم الحفاظ على المحاذاة الرأسية لوقف علامة التبويب ، يتم الحفاظ على نية المؤلف بالكامل.
• يجب أن تكون فواصل الخط حسب مرض التصلب العصبي المتعدد.
• فواصل الصفحة: إذا كانت استراحة الصفحة قد تحدث في منتصف رمز البرنامج ، فيجب استشارة المؤلف مع نقاط كسر الصفحة المفضلة. عادة ما يتم تجنب هذا تماما في أمثلة قصيرة ؛ في البرامج الأطول ، يجب أن يشير المؤلف إلى جميع فترات راحة الصفحات الممكنة في MS.
• اقتباسات: تقليديًا ، يتم استخدام عروض الأسعار "المستقيمة" ، وليس عروض الأسعار المطبعية. يتم تحديد هذا تاريخياً ، من خلال استخدام الخطوط بدون عروض أسعار مطبعية (مثل Courier ، Helvetica) في رمز الكمبيوتر Typeet. ليس مطلوبًا من خلال خصائص التدوين. لا أرى أي سبب ضد استخدام عروض الأسعار المطبعية عند ضبط برامج الكمبيوتر طالما تبقى عروض الأسعار المفردة ، تبقى عروض أسعار مزدوجة ومزدوجة ، أي طالما يتم الحفاظ على عروض الأسعار للمؤلف بدلاً من تصحيحها إلى الممارسة المطبعية القياسية.
• الأرقام: تقليديًا ، تم استخدام الأرقام البطنية دائمًا في رمز البرنامج. إذا كان من الممكن أن تتضايق باستخدام الأرقام القديمة في رمز البرنامج ، أو إذا تم تصميم الخط بهذه الطريقة ، فلا يمكنني رؤية أي سبب ضده. يجب عليك اختيار الخط الذي تكون فيه 1 و I و L (الحالة السفلية L) متميزة ، وكذلك 0 (صفر) و O.