さまざまなプログラミング ソース コードを説明する技術文書を Framemaker で作成する必要があります。
したがって、私のドキュメントは一連のテキストで構成され、その後に一連のソース コード (Java、XML) が続き、その後にさらにテキストなどが続きます。
この質問は、私が Framemaker を使用すべきかどうかではなく、私が使用しなければならないソフトウェアです。. .
私が混乱しているのは、ドキュメントの一部としてソース コードをフォーマットする方法です。誰かが技術文書のためにこれを行い、指示やヒントに出くわしましたか? これまでのところ、私のグーグルは、私がしなければならないことに関連するものを何も生成していません.
少なくとも、コード サンプル用の段落スタイルを作成し、適切な等幅フォントを使用し、ハイフネーションをオフにすることを忘れないでください。
以前これを行っていたときは、テーブル スタイルを作成してそこにコードを貼り付けていたので、その上に素敵なタイトル ヘッダーがあり、少し目立ちました。唯一の注意点は、フレーム テーブル セルが改ページをまたいで分割されないことです。そのため、コードが 1 ページよりも長い場合や、ページの下部に収まる恐れがある場合は、テーブルに複数の行を作成し、行全体にコードを分割します。
数年前にこれについて書いた論文から、来週オンラインで再び利用できるようになります。
タイポグラファーは主に読みやすさに関心を持っており、自然言語でテキストを設定する際に信頼できるツール、慣行、伝統を何百年、何千年も前から持っています。しかし、コンピュータプログラムは自然言語で書かれているわけではありません。それらは「プログラミング言語」、つまり独自の構文規則、独自の表現規則、および独自の読みやすさの基準を持つ人工言語で書かれています。したがって、コンピューター コードは、音楽、数学、化学と同様に、組版の特別な領域です。これらのドメインには独自のルールがありますが、これは自然言語を設定するときに使用されるルールではありません。
コンピューター プログラミング自体は非常に最近の起源であり、それを型に設定する慣行は約 45 年以上さかのぼりません。かなりの量のコンピューター コードが公開されたのは、過去 20 年以内です。関連するタイポグラフィの規律は未熟であるか、実際には存在せず、多くの業界書を調べればわかるように、この分野の実務家のタイポグラフィに対する期待も低いです。改善しようとしない理由はありません。
サンセリフフォントを使用。私の本の 1 つで、同じフォント ファミリを使用しました。テキストには FF Scala を、コードには FF Scala Sans を使用しました。見栄えは良いと思いますが、反対意見もあります。個人的には、これは非常に時代遅れだと思いますが、等幅フォントを使用する必要があるかもしれません。Courier は避けてください。何にも混ざりません。
インデントは表記の一部です。既存の左インデントを尊重する必要があります。ソース コードは既にタブ化されています。各タブをせいぜい 1 つまたは 2 つのスペースに減らします。そうしないと、横方向のスペースが足りなくなります。
空白行を抑えるなど、できるだけ垂直方向のスペースを減らすようにしてください。サンプル全体を 1 ページに収めるようにしてください。それを達成するために、必要に応じて浮かせてください。
改行は表記の一部です。作者に相談せずに改行を追加しないでください。
引用符は表記の一部です。シングルをダブルに、またはその逆に変更しないでください。
正当化: コンピュータ プログラムは、常に左詰め、右詰めで書かれ、表示され、設定されます。
改ページ。本でコンピューター コードを設定する場合、改ページは、自然言語を組版するときに使用される単純な孤立/未亡人の原則に従うだけではありません。代わりに、可能であれば、コードの論理的な「ブロック」をまとめておく必要があります。通常、タイポグラファーがコード内のブロック境界を決定することはできませんが、空白行は通常改ページの許容ポイントです。「ブロック コメント」は、次のコード ブロックで保持する必要があります。これらが何であるかわからない場合は、作者に尋ねてください。
ハイフネーション。プログラミング言語は自然言語ではなく、通常のハイフネーション規則を順守しません。ハイフネーションが必要な場合、または必要ない場合は、作成者に相談してください。著者の指示による場合を除き、プログラム テキスト内の単語をハイフンでつないだり改行したりしてはなりません。
大文字と小文字。プログラム コードの大文字と小文字は、通常、コンピューターにとって重要であり、実質的に常にライターとそのリーダーにとって重要です。大文字と小文字のみが異なり、異なるものを表す単語のペアがよく使用されます。たとえば、BufferedOutputStream と bufferedOutputStream です。プログラマー、特にオーサー・プログラマーは通常、大文字と小文字について非常に体系的であり、タイポグラファー (または他のプログラマー!) にとって必ずしも意味をなさない場合があります。
実用的な推奨事項