非プログラマ向けの組版コードのガイド

バックグラウンド

私はコードを含む科学論文を執筆し、最近、私が原稿からジャーナルのタイプセッターが作成した証拠を受け取りました。結果は受け入れられませんでした。インデントが一貫していません。各コードブロックの最後に完全な停止があります。引用符は破棄されています。すべてのエラーは、使用したプログラミング言語に固有のものではないことに注意してください。

今、私はプログラミングの経験も外部のリソースも持っていない人がそのような過ちを犯すのを見ることができますが、インターネットの時代には誰も外部のリソースなしではいけません。したがって、私は私のお気に入りの検索エンジンに相談して、何か提案するものを検索し、何も見つかりませんでした。LaTeXなどでコードを美しくタイプセットする方法はプログラマー向けのガイドがたくさんありますが、これはすべて適切で適切ですが、これは明らかに他人のコードをタイプセットしなければならないタイプセッター向けではありません。

質問

次のリソースを探しています。

• 組版コードの基本を説明し、
• プログラミング経験のないタイプセッターを対象としています。

たぶん本当のポイントは、コードが実際にタイプセットを理解するようにタイプセットされるべきではないということです。そのため、コードをドキュメントに挿入するときは、すべてのスペース、タブ、特殊文字または特殊文字ではなく、改行もそのままで、そのままそこに配置する必要があります。

• タブの幅は4または8スペースである必要があります（4が最も一般的です）
• フォントは固定幅フォントである必要があります。そして、ほぼ普遍的にする必要があります。

• アプリケーションが置換を行わないことを確認してください！

  つまり、合字はありません。

  また、多くのプログラム（WordやInDesignなど）のアプリケーションは、引用符をタイポグラファーのペアに変更します。ドキュメントにコードを挿入する前に、そのようなオプションが無効になっていることを確認してください。

• コードをある行から別の行に自動的にフローさせないでください。コードに触れないでください、あなたは専門家ではありません！

コードは本文ではなく、表記規則に従っていません。イラストにテキストをタイプセットしますか？

あなたが専門家なら

あなたが専門家であり、問​​題の言語を知っている場合、以下が適用されます。

注：言われたことを読んだり推測したりしないでください。多くの言語は同じように見え、コードは実際のコードのように見える疑似言語である場合があります。その後、次のことができます。

• 置換の固定幅が同じ場合にのみ、キーワードの色付け/太字化/イタライズなどのエディターを実行します。エディターにこれを行わせるのが最善です（たとえばscintillaのようなエディターはフォーマットされたコードをエクスポートできます）。エディターは言語、おそらくライブラリも知っている必要があることに注意してください。

  これを間違えた場合は、善よりも害が大きくなることに注意してください。

あなたがドメインの専門家である場合。言語とライブラリを知り、問題のコードを理解するように：

• レイアウトに合わない場合は、コードを複数の行に再配置できます。あなたが何をしているか本当に理解していない限り、これをしないでください。

  リトマステストは、問題のコードを書いた可能性があります。そうでない場合は、判断することはできません。著者に尋ねてください。

  これに対処するには？プログラマは、コードスタイルの標準を理解しています。提出ガイドラインに、1行にX文字のみを収めることができると書いてください。その後、プログラマーはこれを自分で行うことができます。コードエディタには、このためのツールが頻繁にあります。モノスペースフォントを使用するもう1つの理由。

しかし、あなたはこのすべてを知っていました、結局あなたは専門家でした。作成者にコードの編集を許可します。

行番号？

一部のプログラミング言語およびユースケースでは、行番号が役立つ場合があります。ただし、これは一部の言語では偽物であるため、注意してください。

問題。

何をするにしても、実際には不可能な技術的ハードルに直面する可能性があることに注意してください。コードは本当に組版されるべきではなく、フォーマットされていないテキストであるべきです。これは驚くべき問題につながります。

例：Pythonなどの言語は、Adobe Acrobatなどの多くのPDFビューアーで処理できません。PDFファイルからコードを貼り付けると、エディターは、コピーの貼り付け時に先行スペースを含めないことを決定します。これにより、PDFからエディターにコードを貼り付ける機能が破壊されます。これを処理する良い方法は本当にありません！

もちろん、答えは多くの要因に依存しますが、正しい、適切にフォーマットされたプレーンテキストコードから始めれば、多かれ少なかれここで物事を一般化できます。

ソーステキストの最初の「書式設定」は、 改行文字、スペース文字、タブ文字です。新しい行と（DTPソフトのように）手動改行は同じものではありません、その逆も、いくつかのまれな言語があること注意する 私は、このような聞いたことがないものの、他の書式文字を許可します。

コメントはコードの実行可能な部分ではないため、コメントであるかどうかがわかれば、多くのリスクなしに再フォーマットすることができます。そのため、最初に注目するのは、コメントにタグを付ける方法です。

初期のプレーンテキストの書式設定に関するいくつかの基本は知っておくと良いでしょう。たとえば、Pythonの場合、PEP8スタイルガイドがあります。Python用に作成されたこのフォーマットガイドは、C / C ++やJavaなどの主要言語のリファレンスとして使用できます。さまざまなサンプルプロジェクトを検討すると、疑問がある場合に役立ちます。

したがって、最初の原則は次のとおりです。ソーステキストを変更しないでください。 私はチェックリストに目を通します-それを確認してください：

• どの段階でも文字の自動置換は行われません。
• テキストを編集する必要はありません（100％確実に編集する必要がある場合を除く）。
• 行の折り返しは表示されません。
• インデントは視覚的に保持され、一貫性があります（ インデントレベルごとに約4 x幅）。
• 初期（ゼロ）インデントレベルが表示されます。
• 定義されたスタイルは、構文の書式設定を破壊しません（構文の強調表示が使用されている場合）。
• 元のフォーマットを再確認したり、新たに開始したりできるように、ソースのバックアップをプレーンテキストで保存します。
• 行番号は、存在する場合、特に説明で参照されている場合はそのままにしてください。

実際、元のソースが適切にフォーマットされている場合、行の折り返しはまったくありません。折り返された行がまだ表示されて避けられない場合は、1レベルのぶら下げインデントが最も一般的な解決策です（上記のリンクされたPEPを参照）。改行が必要な場合は、スタイルガイドまたは作成者に相談してください。

それでも、いくつかのマイナーな「空白」文字は置換が必要な場合があります。ソースにはタブ文字を含めることができるため、これは当然、タイプセッターが各行の先頭のすべてのタブが一貫していることを確認する必要があることを意味します。つまり、ネストされたインデントは視覚的に保持され、インデントのすべての次のレベルは同じ幅です（約4 x  インデント1レベルあたりの幅）。

理想的には、スペース文字またはスペースとタブの混合で作成されたインデントは、タブレーション（またはDTPソフトウェアがネストされたインデントに対してより良くできるもの）に置き換えられる必要があるため、必要に応じて、インデントの調整がより簡単になります。
もちろん、スペースを残すこともできますが、フォントを変更する際に幅を管理するのが難しく、表の列のように内側の行のインデントを揃えるのが難しい場合があります。

等幅フォント+スペース

ソースが意図的にスペースでフォーマットされており、等幅フォントのみで読み取ることを意図している場合（たとえば、ASCII-diagramsまたはASCII-art）、スペースを完全に変更せずに保持する必要がありますが、この決定は最初から行う必要があります。この場合、「Courier New」フォントが最も一般的です。それでも本当に必要ない場合、私はモノスペースに反対することをお勧めします。なぜなら、今日のコーディングではモノスペースを選択する人が少なくなり、校正の場合、プロポーショナルフォントがより良い読書体験を提供するからです。

一般に、圧縮された（Arialナローなど）フォントや小さいフォントの方がうまく機能します。本文とは対照的に強調が強くなり、コードがコンパクトになり、不要な行の折り返しが発生する可能性が低くなります。

ここで線を引くことができると思います。上記が行われた場合、少なくとも色のない単純な単一フォントのコードブロックでは、すべてがうまくいく可能性が99％あります。

ツールと高度なフォーマット

さらに、構文の強調表示を使用すると、外観を大幅に改善できます。

• カラー印刷または画面表示：フルカラーレイアウトでは、強調表示のすべての機能を使用できます。したがって、これは最良のシナリオですが、印刷によって色が変更される場合があります。

• グレースケールまたは白黒印刷：もちろん、ここでは太字（キーワードなど）または斜体（コメントなど）を使用できますが、色はすべての結果でグレーに変換されることに注意してください。たとえば、グレー表示されたコメントはディスプレイ上ではきれいに表示されますが、紙上では薄すぎる場合があります。

最も重要な質問は、レイアウトメーカーに、コードを読み取り可能な形式で表現できるツールがあるかどうかです。幸いなことに、コード編集用の無料ツールがたくさんありますが、最も顕著なものは（Windowsの場合）Notepad ++、VSCode、Visual Studioです。ただし、タブからスペースへの暗黙的な自動変換の可能性に注意してください。

Notepad ++には、コードをRTFとしてエクスポートするオプションがあり、ソースのすべての書式設定と構文強調表示が保持されます。

レイアウトでコードプレゼンテーションのテキストフローを変更する必要がない場合は、画像（スクリーンショット）を直接使用できます。テキストほど柔軟ではありませんが、100％の書式設定と行番号を保持し、時間を大幅に節約できます。たとえば、行番号はテキスト形式で保存するのが難しい場合があります。また、PDFへのエクスポートも優れた代替手段です。ただし、すべてのDTPソフトウェアがPDFを埋め込みできるわけではなく、PDFへの印刷時に一部のフォーマットが失われる可能性があります。

たとえば、Notepad ++でのPythonコードのセットアップは次のようになります。

これは、スクリーンショットを直接使用でき、実際には最も簡単な方法であることを説明するためのものです。画面のキャプチャに役立つさまざまなツールがあります。高解像度の画像の場合は、画面を「ステッチ」する必要があります。

配色はもちろん、個々のエディターのスタイルコンフィギュレーターで定義されており、サポートされている言語を既に認識しているため、構文がわからなくても誤った書式を設定することは困難です。ここでは、一般的なタイポグラフィルールが機能するはずです。色の数が多すぎず、フォントが一貫しておらず、インデント、快適な行間隔が必要です。

カスタム言語定義用の追加のツール/プラグインも一般的ですが、それらには構文の知識が必要です。

HTMLには、タグセット<code> ... </ code>があり、リーダー/インタープリターにコンテンツを文字通り絶対に扱うように指示します。また、<pre> ... </ pre>もほとんど同じです。出版のために式、方程式、コードをタイプセットしなければならないことが多かったので、IMAGESを使用してこれを行うことも推奨します...問題のあるアイテムの.gifまたは.jpgまたは.pngを作成します。

もう1つの要素は、コードが本文テキストではないことを読者にセマフォまたは電信で送信するため、コードが伝統的にCourierモノスペースまたはその他のモノスペースフォントでレンダリングされることです。私はこのスタイルの選択を購読していますが、それはとても理にかなっていると思います。

ほとんどの「レガシー」組版システムでは、適度に複雑な数学方程式は、耐え難いほど時間がかかり、エラーに満ちていました。