|
| 1 | +:navigation-title: Inline Code |
1 | 2 |
|
2 | 3 | .. include:: /Includes.rst.txt |
3 | | -.. index:: |
4 | | - reST; Inline code |
5 | | -.. _Inline-Code: |
6 | | - |
7 | | -======================== |
8 | | -Inline code & text roles |
9 | | -======================== |
| 4 | +.. _inline-code: |
10 | 5 |
|
| 6 | +==================================== |
| 7 | +Inline code with or without overlays |
| 8 | +==================================== |
11 | 9 |
|
12 | 10 | .. hint:: |
13 | 11 |
|
14 | | - Too much inline code can make the information on a page highly |
15 | | - unreadable. If this is the case, consider using |
16 | | - :ref:`writing-rest-codeblocks-with-syntax-highlighting`. |
17 | | - |
18 | | - |
19 | | -.. index:: reST; Markup |
20 | | - |
21 | | -How to semantically mark up specific text |
22 | | -========================================= |
23 | | - |
24 | | -There are several ways to semantically mark specific parts of the text. The main goal is to be able to use |
25 | | -a consistent style for specific parts of the text, for example code fragments, file names and GUI |
26 | | -elements. |
27 | | - |
28 | | -.. index:: reST; Text roles |
29 | | -.. _text-roles: |
30 | | - |
31 | | -Using text roles |
32 | | ----------------- |
33 | | - |
34 | | -1. **Preferred:** Use `Sphinx interpreted text roles <http://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html>`__ |
35 | | - to explicitly specify what kind of text / code (text role) it is. This shows |
36 | | - the semantics and in the output there may be a a special coloring or highlighting: |
37 | | - |
38 | | - ================ ================================================= ============================================= ==== |
39 | | - Role Source Output Note |
40 | | - ================ ================================================= ============================================= ==== |
41 | | - (default) ```result = (1 + x) * 32``` `result = (1 + x) * 32` This works because in :file:`Includes.rst.txt` we set the default role to ``:code:`...``` |
42 | | - |
43 | | - aspect ``:aspect:`Description:``` :aspect:`Description:` For better optics |
44 | | - bash ``:bash:`find . -type d | grep typo3``` :bash:`find . -type d | grep typo3` |
45 | | - css ``:css:`.h1 {font-size:150%}``` :css:`.h1 {font-size:150%}` |
46 | | - html ``:html:`<a href="#">``` :html:`<a href="#">` |
47 | | - issue ``:issue:`12345``` :issue:`12345` To link to a TYPO3 issue. |
48 | | - js ``:js:`var f = function () {return 1;}``` :js:`var f = function () {return 1;}` |
49 | | - php ``:php:`$result = $a + 23;``` :php:`$result = $a + 23;` |
50 | | - rst ``:rst:`.. image:: /path/to/img.jpg``` :rst:`.. image:: /path/to/img.jpg` |
51 | | - sep ``:sep:`|``` :sep:`|` To give the separator '\|' a special style in some contexts like :ref:`Styled-Definition-Lists` |
52 | | - sql ``:sql:`SELECT * FRAM pages WHERE hidden=0;``` :sql:`SELECT * FRAM pages WHERE hidden=0;` |
53 | | - typoscript ``:typoscript:`lib.hello.value = Hello World!``` :typoscript:`lib.hello.value = Hello World!` |
54 | | - xml ``:xml:`<?xml version="1.0" encoding="UTF-8"?>``` :xml:`<?xml version="1.0" encoding="UTF-8"?>` |
55 | | - yaml ``:yaml:`- {name: John Smith, age: 33}``` :yaml:`- {name: John Smith, age: 33}` |
56 | | - ================ ================================================= ============================================= ==== |
57 | | - |
58 | | - |
59 | | - |
60 | | - |
61 | | - |
62 | | - `Standard Sphinx interpreted text roles |
63 | | - <http://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#other-semantic-markup>`__: |
64 | | - |
65 | | - ================ ================================================= ============================================ === |
66 | | - Role Source Output Note |
67 | | - ================ ================================================= ============================================ === |
68 | | - abbr ``:abbr:`LIFO (last-in, first-out)``` :abbr:`LIFO (last-in, first-out)` An abbreviation. If the role content contains a parenthesized explanation, it will be treated specially: it will be shown in a tool-tip in HTML, and output only once in LaTeX. |
69 | | - code ``:code:`result = (1 + x) * 32``` :code:`result = (1 + x) * 32` |
70 | | - command ``:command:`rm``` :command:`rm` The name of an OS-level command, such as rm. |
71 | | - dfn ``:dfn:`something``` :dfn:`something` Mark the defining instance of a term in the text. (No index entries are generated.) |
72 | | - file ``:file:`/etc/passwd``` :file:`/etc/passwd` |
73 | | - guilabel ``:guilabel:`&Cancel```, :guilabel:`&Cancel`, Labels presented as part of an interactive user interface should be marked using guilabel. This includes labels from text-based interfaces such as those created using curses or other text-based libraries. Any label used in the interface should be marked with this role, including button labels, window titles, field names, menu and menu selection names, and even values in selection lists. |
74 | | - ``:guilabel:`O&k```, :guilabel:`O&k`, |
75 | | - ``:guilabel:`&Reset```, :guilabel:`&Reset`, |
76 | | - ``:guilabel:`F&&Q``` :guilabel:`F&&Q` |
77 | | - kbd ``Press :kbd:`ctrl` + :kbd:`s``` Press :kbd:`ctrl` + :kbd:`s` Mark a sequence of keystrokes. What form the key sequence takes may depend on platform- or application-specific conventions. When there are no relevant conventions, the names of modifier keys should be spelled out, to improve accessibility for new users and non-native speakers. For example, an xemacs key sequence may be marked like :kbd:`C` + :kbd`x`, :kbd:`C` + :kbd:`f`, but without reference to a specific application or platform, the same sequence should be marked as :kbd:`ctrl` + :kbd:`x`, :kbd:`ctrl` + :kbd:`f`. |
78 | | - mailheader ``:mailheader:`Content-Type``` :mailheader:`Content-Type` The name of an RFC 822-style mail header. This markup does not imply that the header is being used in an email message, but can be used to refer to any header of the same “style.” This is also used for headers defined by the various MIME specifications. The header name should be entered in the same way it would normally be found in practice, with the camel-casing conventions being preferred where there is more than one common usage. |
79 | | - ref ``:ref:`Inline-Code``` :ref:`Inline-Code` Sphinx cross-referencing |
80 | | - ================ ================================================= ============================================ === |
81 | | - |
82 | | - `Standard Docutils interpreted text roles |
83 | | - <http://docutils.sourceforge.net/docs/ref/rst/roles.html#standard-roles>`__: |
84 | | - |
85 | | - .. tip:: |
86 | | - |
87 | | - For more information about the `ref` directive, see :ref:`how-to-document-hyperlinks`. |
88 | | - |
89 | | - ================== ================================================= ============================================ === |
90 | | - Role Source Output Note |
91 | | - ================== ================================================= ============================================ === |
92 | | - emphasis ``:emphasis:`text`, *text*`` :emphasis:`text`, *text* |
93 | | - literal ``:literal:`\ \ abc``` :literal:`\ \ abc` |
94 | | - literal ``:literal:`text`, ''text''`` (backticks!) :literal:`text`, ``text`` |
95 | | - math ``:math:`A_\text{c} = (\pi/4) d^2``` :math:`A_\text{c} = (\pi/4) d^2` The math role marks its content as mathematical notation (inline formula). The input format is LaTeX math syntax without the “math delimiters“ ($ $). |
96 | | - rfc, rfc-reference ``:RFC:`2822``` :RFC:`2822` |
97 | | - strong ``:strong:`text`, **text**`` :strong:`text`, **text** Implements strong emphasis. |
98 | | - subscript ``:subscript:`subscripted``` :subscript:`subscripted` |
99 | | - superscript ``:superscript:`superscripted``` :superscript:`superscripted` |
100 | | - t, title-reference ``:t:`Design Patterns``` :t:`Design Patterns` The :title-reference: role is used to describe the titles of books, periodicals, and other materials. |
101 | | - ================== ================================================= ============================================ === |
102 | | - |
103 | | - |
104 | | -2. As an alternative, you can use the default text role for small inline |
105 | | - code snippets, but it is better to use specific text roles. However, if no |
106 | | - text role exists, you may use this to mark the text. |
107 | | - |
108 | | - Surround the code by *single backticks* and don't start or end |
109 | | - the code with whitespace. Example: Type ```2 + 2 = 4``` to get `2 + 2 = 4` |
110 | | - as result. |
111 | | - |
112 | | -3. Just write the code as it is. This may make the text more difficult to read. |
113 | | - Use your common sense. |
114 | | - |
115 | | -.. index:: reST; Literal code |
116 | | - |
117 | | -When to use literal code \`\`...`` |
118 | | ----------------------------------- |
119 | | - |
120 | | -Things get tricky if your inline code already contains single backquotes (backticks). |
121 | | - |
122 | | -4. In many cases you can still use the *interpreted text role* as described in 1. to 3. |
123 | | - For example we can write ``:code:`:html:`<br>```` to get :code:`:html:`<br>`` |
124 | | - |
125 | | - This is possible if (a) your code doesn't start with a backtick and (b) if no backtick in |
126 | | - your code has a trailing whitespace. |
127 | | - |
128 | | -5. **But:** To be really free to include inline any code containing backticks you will want to use |
129 | | - `inline literals`_. Again: Don't escape or double anything, whitespace is maintained. |
130 | | - *Example:* |
131 | | - |
132 | | - Write:: |
133 | | - |
134 | | - SQL-example code: ``SELECT `tt_content` . `bodytext` AS `t1` . `text`;`` |
135 | | - |
136 | | - to get: |
137 | | - |
138 | | - SQL-example code: ``SELECT `tt_content` . `bodytext` AS `t1` . `text`;`` |
139 | | - |
140 | | - **The drawbacks** of literal inline code notation are: |
141 | | - |
142 | | - * there is no way to semantically classify the kind of code |
143 | | - * there is no special coloring or highlighting |
144 | | - * the raw reST code looks less beautiful and is less readable |
145 | | - |
146 | | -.. _interpreted text roles: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#interpreted-text |
147 | | -.. _inline literals: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#inline-literals |
148 | | - |
149 | | -Inline code versus code blocks |
150 | | -============================== |
151 | | - |
152 | | -The name for - very - small code snippets that occur within normal text flow |
153 | | -within sentences is *inline code*. |
154 | | - |
155 | | -*inline code* |
| 12 | + Too much inline code can make the information on a page |
| 13 | + unreadable. If this is the case, consider using |
| 14 | + `Code blocks with syntax highlighting <https://docs.typo3.org/permalink/h2document:writing-rest-codeblocks-with-syntax-highlighting>`_. |
156 | 15 |
|
157 | | -* is styled somewhat differently, |
158 | | -* has **no** syntax highlighting, |
159 | | -* does **not** need to be syntactically correct, |
160 | | -* can be compared to `<span>...</span>` tags in html |
| 16 | +Any text inside single or double backticks is printed as inline code. Double |
| 17 | +backticks allow unescaped backticks to be used in the code: |
161 | 18 |
|
162 | | -In contrast, *code-blocks* |
| 19 | +.. tabs:: |
163 | 20 |
|
164 | | -* appear "as a box", |
165 | | -* can have syntax highlighting, |
166 | | -* need to be syntactically correct in order to have highlighting, |
167 | | -* can be compared to `<pre>...</pre>` blocks in html, |
168 | | -* use predefined names for the different languages that come with Pygments, |
169 | | - the syntax highlighter. |
| 21 | + .. group-tab:: Output |
170 | 22 |
|
| 23 | + .. include:: _snippets/_inline-code.rst.txt |
171 | 24 |
|
172 | | -Definition of text roles |
173 | | -======================== |
| 25 | + .. group-tab:: reST |
174 | 26 |
|
175 | | -For all officials TYPO3 manuals `php` is set as default highlight |
176 | | -language with the exception of the TypoScript manuals, where `typoscript` is |
177 | | -the default. |
| 27 | + .. literalinclude:: _snippets/_inline-code.rst.txt |
178 | 28 |
|
179 | | -You need a custom text role? |
180 | | ----------------------------- |
| 29 | +By convention single backticks are used unless double are needed. |
181 | 30 |
|
182 | | -You need another 'language' to mark up inline? |
| 31 | +.. _inline-code-language: |
183 | 32 |
|
184 | | -You are free to define additional text roles *in your project* or even |
185 | | -*on an individual page* as you like. Make use of the `role directive |
186 | | -<http://docutils.sourceforge.net/docs/ref/rst/directives.html#role>`__. |
187 | | -Example: You want 'haskell'? Define that role as derivative of 'code': |
| 33 | +Code roles with language information and overlay |
| 34 | +================================================ |
188 | 35 |
|
189 | | -.. code-block:: rst |
| 36 | +You can also use text roles with one of the predefined languages to display more |
| 37 | +information to the user. For the most common languages, automatic |
| 38 | +detection provides more context for the user. |
190 | 39 |
|
191 | | - .. role:: haskell(code) |
| 40 | +.. tabs:: |
192 | 41 |
|
193 | | -You may then write: |
| 42 | + .. group-tab:: Output |
194 | 43 |
|
195 | | -.. code-block:: rst |
| 44 | + .. include:: _snippets/_inline-code-languages.rst.txt |
196 | 45 |
|
197 | | - Here is some :haskell:`haskell inline code` in the sentence. |
| 46 | + .. group-tab:: reST |
198 | 47 |
|
199 | | -The immediate advantage will be that you can explicitly markup your source |
200 | | -code semantically and declare snippets to be 'Haskell'. The visual appearance |
201 | | -will be that of 'code' until a special css class has been defined. Feel free to |
202 | | -open a request `here |
203 | | -<https://github.com/TYPO3-Documentation/t3SphinxThemeRtd/issues>`__. Look at |
204 | | -this html to understand the technical background: |
| 48 | + .. literalinclude:: _snippets/_inline-code-languages.rst.txt |
205 | 49 |
|
| 50 | +PHP classes from the TYPO3 Core are automatically linked to https://api.typo3.org |
| 51 | +and display the PHP doc comment (if any) in the overlay. |
206 | 52 |
|
207 | | -.. code-block:: html |
| 53 | +All named inline code roles show an overlay where the code can be conveniently |
| 54 | +copied and information on the language of the code. |
208 | 55 |
|
209 | | - <code class="code haskell docutils literal"> |
210 | | - <span class="pre">haskell inline code</span> |
211 | | - </code> |
| 56 | +.. seealso:: |
212 | 57 |
|
213 | | -A default styling for :html:`class="code"` exists and is in effect until |
214 | | -overridden by a special styling :html:`class="code.haskell"` that needs to |
215 | | -be defined. |
| 58 | + * `API links: More information on TYPO3 PHP classes <https://docs.typo3.org/permalink/h2document:links-api>`_ |
0 commit comments