はじめに
こんにちは、Sphinx-Users.jpの賑やかし担当です。さて、翻訳などをしていて文章中に引用などでURLが1パラグラフ中に多発することがあります。reSTでそれをどう書くかちょっと考えました。
元のHTML
ここで黄緑になっているところがハイパーリンクになっている。これをreST化する必要があったのでしていたときに、上に書いたような問題がありました。
方法
直接URLを書く
これはreSTの表記は汚くなるけど、見た目そのままという意味では分かりやすい書き方。またパラグラフ間の改行も変更がありません。
It also contains the usual functions to read and/or write from files such as: `file:open/2 <http://erldocs.com/R14B/kernel/file.html#open/2>`_ and `file:close/1 <http://erldocs.com/R14B/kernel/file.html#close/1>`_ to do as their names say (opening and closing files!), `file:read/2 <http://erldocs.com/R14B/kernel/file.html#read/2>`_ to get the content a file (either as string or a binary), `file:read_line/1 <http://erldocs.com/R14B/kernel/file.html#read_line/1>`_ to read a single line, `file:position/3 <http://erldocs.com/R14B/kernel/file.html#position/3>`_ to move the pointer of an open file to a given position, etc.
間接的にURLを書く
これは上と同様の囲みが必要ですが、非常に見た目がすっきりします。また同じリンク先が出てきた場合にはURLを省略できる利点があります。パラグラフ間にリンクが増えるのでちょっと可読性は下がります。
It also contains the usual functions to read and/or write from files such as: `file:open/2`_ and `file:close/1`_ to do as their names say (opening and closing files!), `file:read/2`_ to get the content a file (either as string or a binary), `file:read_line/1`_ to read a single line, `file:position/3`_ to move the pointer of an open file to a given position, etc. .. _file:open/2: http://erldocs.com/R14B/kernel/file.html#open/2 .. _file:close/1: http://erldocs.com/R14B/kernel/file.html#close/1 .. _file:read/2: http://erldocs.com/R14B/kernel/file.html#read/2 .. _file:read_line/1: http://erldocs.com/R14B/kernel/file.html#read_line/1 .. _file:position/3: http://erldocs.com/R14B/kernel/file.html#position/3
リンクターゲットに名前を付ける
この書き方の場合はパラグラフ間にリンクが増えるけど、パラグラフ自体のreSTは上のものと同様すっきりします。またURLの簡略名も短くしようと思えばできるので、リンク先を切り替える必要がある、などの場合に便利かもしれません。
It also contains the usual functions to read and/or write from files such as: `file:open/2`__ and `file:close/1`__ to do as their names say (opening and closing files!), `file:read/2`__ to get the content a file (either as string or a binary), `file:read_line/1`__ to read a single line, `file:position/3`__ to move the pointer of an open file to a given position, etc. .. _file.open.2: http://erldocs.com/R14B/kernel/file.html#open/2 .. _file.close.1: http://erldocs.com/R14B/kernel/file.html#close/1 .. _file.read.2: http://erldocs.com/R14B/kernel/file.html#read/2 .. _file.read_line.1: http://erldocs.com/R14B/kernel/file.html#read_line/1 .. _file.position.3: http://erldocs.com/R14B/kernel/file.html#position/3 __ file.open.2_ __ file.close.1_ __ file.read.2_ __ file.read_line.1_ __ file.position.3_