docutils/tools/editors/emacs/IDEAS.rst

   1 The following is a list of ideas of functionality which would be nice
   2 to have in `rst.el`. In the examples a ``@`` stands for the cursor.
   3
   4 Convert to id
   5 =============
   6
   7 * Convert the region to an HTML id
   8
   9   * For instance "Eine Überschrift" to "eine-berschrift"
  10
  11   * According the same rules as reST does this
  12
  13 Jump to internal target
  14 =======================
  15
  16 * A command to jump to the internal target the point is on
  17
  18 * A target may be
  19
  20   * A section title
  21
  22   * Footnotes / citations
  23
  24   * Inline internal targets
  25
  26   * Hyperlink target definition
  27
  28   * Substitution definition
  29
  30 * See hunk #26 in `rst_el-emacs_V23_1_patch1_1_2` vs. `emacs_V23_1`
  31   for some ideas
  32
  33 Completion for directive options
  34 ================================
  35
  36 * Imagine ::
  37
  38     .. list-table::
  39        :@
  40
  41   with the cursor at the asterisk
  42
  43 * There should be a command which offers all the possible options for
  44   this particular directive as completion
  45
  46 * May be `skeleton.el` can also be useful
  47
  48 Completion for directives
  49 =========================
  50
  51 * Imagine ::
  52
  53     .. @
  54
  55 * There should be a command which offers all directives as completion
  56
  57 * May be this should work for other keywords as well
  58
  59 * May be this could work even at the beginning of the line
  60
  61 * Completion must be bound to M-TAB
  62
  63   * Already existing binding must be chained
  64
  65   * May be `expand.el` can help (look in package finder)?
  66
  67   * May be `hippie` is good here
  68
  69   * Check `(info)autotype`
  70
  71 Completion for user-defined elements
  72 ====================================
  73
  74 * Imagine ::
  75
  76     |@
  77
  78   or ::
  79
  80     [@
  81
  82   or ::
  83
  84     _@
  85
  86 * There should be a command which offers all defined substitutions /
  87   footnotes / links as completion
  88
  89 Insertion of link alias
  90 =======================
  91
  92 * Imagine ::
  93
  94     Aspect of something
  95     ===================
  96
  97     This is about the `aspect of something`_@
  98
  99 * There should be a command which asks you for an alias for the link,
 100   add the alias and change the link ::
 101
 102     .. _aspects of something:
 103
 104     Aspect of something
 105     ===================
 106
 107     This is about the `aspects of something`_@
 108
 109 Smart use of `iimage-mode`
 110 ==========================
 111
 112 * There is `iimage-mode` which shows ``.. image::``\s in Emacs
 113
 114 * May be we can add a binding to toggle it
 115
 116 TOC in speedbar
 117 ===============
 118
 119 * If the TOC is displayed in the speedbar this could be used for
 120   permanent navigation
 121
 122 toc-mode without markup
 123 =======================
 124
 125 * The markup which may be contained in a section title is not useful
 126   in toc-mode and should be suppressed
 127
 128 Sophisticated navigation in sections
 129 ====================================
 130
 131 * Navigation in sections similar to navigation in other structured data
 132
 133   * Like XML, Lisp
 134
 135   * C-M-u für Up
 136
 137   * C-M-d für Down
 138
 139   * C-M-f / C-M-b für Forward / Backward
 140
 141 Display of current location
 142 ===========================
 143
 144 * Display the "section path" to the current point
 145
 146 * Like in XML: In which element is the point?
 147
 148 toc-mode only to a certain level
 149 ================================
 150
 151 * If a TOC buffer is created a prefix argument should limit the depth
 152   of the listing to the given level
 153
 154 Imenu support
 155 =============
 156
 157 * Imenu could be supported
 158
 159   * See `(elisp)Imenu`
 160
 161 Outline support
 162 ===============
 163
 164 * Support for `outline-mode` / `allout-mode` would be nice
 165
 166   * Should consider section titles
 167
 168     * May be item lists can also be included
 169
 170   * Using `allout-mode` is difficult
 171
 172     * It's not customizable enough for the complex syntax of
 173       reStructuredText
 174
 175     * However, some commands make sense
 176
 177       * Motion commands
 178
 179       * Exposure commands
 180
 181       * Some alteration commands
 182
 183     * Should be reimplemented
 184
 185       * Key bindings need to be reused
 186
 187         * However, care must be taken if a file uses `allout-mode` for
 188           instance by comment strings
 189
 190         * In this case key bindings must not be overridden
 191
 192   * A command adding / updating `allout-mode` tags could be a solution
 193
 194 Sophisticated filling
 195 =====================
 196
 197 * These things must be filled special:
 198
 199   * Definitions
 200
 201   * Filling of ::
 202
 203       * VeryLongWordSuchAsAnURLVeryLongWordSuchAsAnURLVeryLongWordSuchAsAnURLVeryLongWordSuchAsAnURLVeryLongWordSuchAsAnURL
 204
 205     should work as expected by *not* breaking the line
 206
 207 * These things may not be filled at all
 208
 209   * Literal blocks
 210
 211   * Tables
 212
 213   * Section headers
 214
 215   * Link definitions
 216
 217 Sophisticated indentation
 218 =========================
 219
 220 * It should be generally possible to shift one more to the right
 221
 222   * This makes indentation for quotes possible
 223
 224   * But not for literal blocks
 225
 226 * For item lists the best tab should be on the same level as the last
 227   item::
 228
 229     * bla
 230
 231     @
 232
 233   * The second best tab should be where text starts::
 234
 235       * bla
 236
 237         @
 238
 239 * <backtab> should be used to indent in the other direction
 240
 241   * Or may be C-u <tab> but this has a different meaning
 242
 243 * <tab> could obsolete C-c C-r <tab>
 244
 245   * For this the indentation needs to be determined at the start
 246     instead of per line
 247
 248     * <tab> over list works::
 249
 250         Text
 251
 252           * GGGGGG
 253           * SSSSSSSSSSSSSSS
 254           * TTTTTTTT
 255           * ZZZZZZZZ
 256
 257     * <tab> over list doesn't work::
 258
 259         Text
 260
 261         * GGGGGG
 262         * SSSSSSSSSSSSSSS
 263         * TTTTTTTT
 264         * ZZZZZZZZ
 265
 266 List to sections
 267 ================
 268
 269 * A command would be nice which
 270
 271   * transforms the first level of a nested list in a region into a
 272     header
 273
 274   * removes one level of indentation from the rest of the list
 275
 276 Change section level by more than one step
 277 ==========================================
 278
 279 * It would be nice if <C-h> `rst-adjust` could rotate a section
 280   adornment more than one level
 281
 282 * A modification of the semantic of the prefix arguments could do this
 283
 284   * Non-zero numeric prefix arg n rotates n step in the given direction
 285
 286   * Prefix arg 0 toggles overline / underline
 287
 288     * This would be different from current setup
 289
 290 Compiling for syntax check
 291 ==========================
 292
 293 * Compiling with results going to `/dev/null` would be useful
 294
 295   * This would just do a syntax check with no files lying around
 296
 297 * Toolset choice for <C-c C-c C-c> `rst-compile` must be by
 298   customizable if at all necessary
 299
 300   * Customization group must be used
 301
 302 Renumber an exisiting enumeration
 303 =================================
 304
 305 * Renumbering an exisiting enumeration is not possible yet
 306
 307 Command to move across blocks
 308 =============================
 309
 310 * A command moving forward / backward across the content blocks of the
 311   current block would be nice
 312
 313   * For instance: Move across all blocks contained in an item or field
 314
 315   * This would move to the start of the sibling of the current block
 316
 317   * Would allow to jump to the next item on the same level in a list
 318
 319 * <C-M-f> `forward-sexp` could be a nice binding
 320
 321 rst-toc-insert features
 322 =======================
 323
 324 * The `contents::` options could be parsed to figure out how deep to
 325   render the inserted TOC
 326
 327 * On load, detect any existing TOCs and set the properties for links
 328
 329 * TOC insertion should have an option to add empty lines
 330
 331 * TOC insertion should deal with multiple lines
 332
 333 * Automatically detect if we have a `section-numbering::` in the
 334   corresponding section, to render the toc.
 335
 336 Automatic handling of `.txt` files
 337 ----------------------------------
 338
 339 It would be nice to differentiate between text files using
 340 reStructuredText and other general text files. If we had a function to
 341 automatically guess whether a `.txt` file is following the
 342 reStructuredText conventions, we could trigger `rst-mode` without
 343 having to hard-code this in every text file, nor forcing the user to
 344 add a local mode variable at the top of the file. We could perform
 345 this guessing by searching for a valid adornment at the top of the
 346 document or searching for reStructuredText directives further on.
 347
 348 Entry level for rst-straighten-adornments
 349 -----------------------------------------
 350
 351 * `rst-straighten-adornments` should have an entry level to start at a
 352   lower than the top level
 353
 354   * I for one prefer a verbose style for top level titles which is not
 355     appropriate for documents without titles
 356
 357   * Should be done by a prefix argument