restructuredtextasciidoc

How to write callouts using reStructuredText?


Asciidoc supports callouts. How can one write similar callouts using reStructuredText?


Solution

  • There does not seem to be a built-in equivalent, but it is easy to make something that looks similar to the example given in the asciidoc documentation:

    .. topic:: MS-DOS directory listing
    
       ::
    
         10/17/97   9:04         <DIR>    bin
         10/16/97  14:11         <DIR>    DOS            <1>
         10/16/97  14:40         <DIR>    Program Files
         10/16/97  14:46         <DIR>    TEMP
         10/17/97   9:04         <DIR>    tmp
         10/16/97  14:37         <DIR>    WINNT
         10/16/97  14:25             119  AUTOEXEC.BAT   <2>
          2/13/94   6:21          54,619  COMMAND.COM    <2>
         10/16/97  14:25             115  CONFIG.SYS     <2>
         11/16/97  17:17      61,865,984  pagefile.sys
         2/13/94   6:21           9,349  WINA20.386      <3>
    
       1. This directory holds MS-DOS.
       2. System startup code for DOS.
       3. Some sort of Windows 3.1 hack.
    

    The only thing this lacks is the highlights on the markers. If those are very important to you, you can use a parsed-literal block:

    .. topic:: MS-DOS directory listing
    
       .. parsed-literal::
    
          10/17/97   9:04         <DIR>    bin
          10/16/97  14:11         <DIR>    DOS            **<1>**
          10/16/97  14:40         <DIR>    Program Files
          10/16/97  14:46         <DIR>    TEMP
          10/17/97   9:04         <DIR>    tmp
          10/16/97  14:37         <DIR>    WINNT
          10/16/97  14:25             119  AUTOEXEC.BAT   **<2>**
           2/13/94   6:21          54,619  COMMAND.COM    **<2>**
          10/16/97  14:25             115  CONFIG.SYS     **<2>**
          11/16/97  17:17      61,865,984  pagefile.sys
          2/13/94   6:21           9,349  WINA20.386      **<3>**
    
       1. This directory holds MS-DOS.
       2. System startup code for DOS.
       3. Some sort of Windows 3.1 hack.
    

    Should you have very many of these callouts, then I suggest making a custom directive for them.