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   * Probably `imenu` functionality can be used for this
 123
 124     * See `imenu` documentation and `speedbar-use-imenu-flag`
 125
 126   * See `speedbar`
 127
 128 toc-mode without markup
 129 =======================
 130
 131 * The markup which may be contained in a section title is not useful
 132   in toc-mode and should be suppressed
 133
 134 Sophisticated navigation in sections
 135 ====================================
 136
 137 * Navigation in sections similar to navigation in other structured data
 138
 139   * Like XML, Lisp
 140
 141   * C-M-u für Up
 142
 143   * C-M-d für Down
 144
 145   * C-M-f / C-M-b für Forward / Backward
 146
 147 Display of current location
 148 ===========================
 149
 150 * Display the "section path" to the current point
 151
 152 * Like in XML: In which element is the point?
 153
 154 toc-mode only to a certain level
 155 ================================
 156
 157 * If a TOC buffer is created a prefix argument should limit the depth
 158   of the listing to the given level
 159
 160 Imenu support or similar
 161 ========================
 162
 163 * Imenu could be supported
 164
 165   * See `(elisp)Imenu`
 166
 167 * `etags` could be supported
 168
 169   * See `(emacs)Tags` and `etags.el`
 170
 171   * May be this can be used for generating HTML local tags somehow?
 172
 173     * As requested by `Convert to id`_
 174
 175     * Could use `complete-tag`
 176
 177 Outline support
 178 ===============
 179
 180 * Support for `outline-mode` / `allout-mode` would be nice
 181
 182   * Should consider section titles
 183
 184     * May be item lists can also be included
 185
 186   * Using `allout-mode` is difficult
 187
 188     * It's not customizable enough for the complex syntax of
 189       reStructuredText
 190
 191     * However, some commands make sense
 192
 193       * Motion commands
 194
 195       * Exposure commands
 196
 197       * Some alteration commands
 198
 199     * Should be reimplemented
 200
 201       * Key bindings need to be reused
 202
 203         * However, care must be taken if a file uses `allout-mode` for
 204           instance by comment strings
 205
 206         * In this case key bindings must not be overridden
 207
 208   * A command adding / updating `allout-mode` tags could be a solution
 209
 210 Sophisticated filling
 211 =====================
 212
 213 * These things must be filled special:
 214
 215   * Definitions
 216
 217   * Filling of ::
 218
 219       * VeryLongWordSuchAsAnURLVeryLongWordSuchAsAnURLVeryLongWordSuchAsAnURLVeryLongWordSuchAsAnURLVeryLongWordSuchAsAnURL
 220
 221     should work as expected by *not* breaking the line
 222
 223   * May be `fill-nobreak-predicate` can help here
 224
 225 * These things may not be filled at all
 226
 227   * Literal blocks
 228
 229   * Tables
 230
 231   * Link definitions
 232
 233   * May be `fill-nobreak-predicate` can help here, too
 234
 235 * May be defining an own `auto-fill-function` may be useful
 236
 237   * Might prevent auto-filling of literal text
 238
 239 * Filling of a re-indented item doesn't work as expected::
 240
 241     * Something just indented once more by the user
 242     though continuation line is not indented already
 243
 244   * Alternatively indentation could indent the whole item
 245
 246     * See `Sophisticated indentation`_
 247
 248 * See also `Filling of section headers`_
 249
 250 Sophisticated indentation
 251 =========================
 252
 253 * It should be generally possible to shift one more to the right
 254
 255   * This makes indentation for quotes possible
 256
 257   * But not for literal blocks
 258
 259 * For item lists the best tab should be on the same level as the last
 260   item::
 261
 262     * bla
 263
 264     @
 265
 266   * The second best tab should be where text starts::
 267
 268       * bla
 269
 270         @
 271
 272 * <backtab> should be used to indent in the other direction
 273
 274   * Or may be C-u <tab> but this has a different meaning
 275
 276 * <tab> could obsolete C-c C-r <tab>
 277
 278   * For this the indentation needs to be determined at the start
 279     instead of per line
 280
 281     * <tab> over list works::
 282
 283         Text
 284
 285           * GGGGGG
 286           * SSSSSSSSSSSSSSS
 287           * TTTTTTTT
 288           * ZZZZZZZZ
 289
 290     * <tab> over list doesn't work::
 291
 292         Text
 293
 294         * GGGGGG
 295         * SSSSSSSSSSSSSSS
 296         * TTTTTTTT
 297         * ZZZZZZZZ
 298
 299 * An indenting tab on the head of a list item should indent the whole
 300   list item instead of only the first line
 301
 302   * Alternatively `fill-paragraph` could do so
 303
 304     * See `Sophisticated filling`_
 305
 306 * May be `refill-mode` can be useful
 307
 308 List to sections
 309 ================
 310
 311 * A command would be nice which
 312
 313   * transforms the first level of a nested list in a region into a
 314     header
 315
 316   * removes one level of indentation from the rest of the list
 317
 318 Change section level by more than one step
 319 ==========================================
 320
 321 * It would be nice if <C-h> `rst-adjust` could rotate a section
 322   adornment more than one level
 323
 324 * A modification of the semantic of the prefix arguments could do this
 325
 326   * Non-zero numeric prefix arg n rotates n step in the given direction
 327
 328   * Prefix arg 0 toggles overline / underline
 329
 330     * This would be different from current setup
 331
 332 Compiling for syntax check
 333 ==========================
 334
 335 * Compiling with results going to `/dev/null` would be useful
 336
 337   * This would just do a syntax check with no files lying around
 338
 339 * Toolset choice for <C-c C-c C-c> `rst-compile` must be by
 340   customizable if at all necessary
 341
 342   * Customization group must be used
 343
 344 Renumber an exisiting enumeration
 345 =================================
 346
 347 * Renumbering an exisiting enumeration is not possible yet
 348
 349 Command to move across blocks
 350 =============================
 351
 352 * A command moving forward / backward across the content blocks of the
 353   current block would be nice
 354
 355   * For instance: Move across all blocks contained in an item or field
 356
 357   * This would move to the start of the sibling of the current block
 358
 359   * Would allow to jump to the next item on the same level in a list
 360
 361 * <C-M-f> `forward-sexp` could be a nice binding
 362
 363 rst-toc-insert features
 364 =======================
 365
 366 * The `contents::` options could be parsed to figure out how deep to
 367   render the inserted TOC
 368
 369 * On load, detect any existing TOCs and set the properties for links
 370
 371 * TOC insertion should have an option to add empty lines
 372
 373 * TOC insertion should deal with multiple lines
 374
 375 * Automatically detect if we have a `section-numbering::` in the
 376   corresponding section, to render the toc.
 377
 378 Automatic handling of `.txt` files
 379 ==================================
 380
 381 It would be nice to differentiate between text files using
 382 reStructuredText and other general text files. If we had a function to
 383 automatically guess whether a `.txt` file is following the
 384 reStructuredText conventions, we could trigger `rst-mode` without
 385 having to hard-code this in every text file, nor forcing the user to
 386 add a local mode variable at the top of the file. We could perform
 387 this guessing by searching for a valid adornment at the top of the
 388 document or searching for reStructuredText directives further on.
 389
 390 Entry level for rst-straighten-adornments
 391 =========================================
 392
 393 * `rst-straighten-adornments` should have an entry level to start at a
 394   lower than the top level
 395
 396   * I for one prefer a verbose style for top level titles which is not
 397     appropriate for documents without titles
 398
 399   * Should be done by a prefix argument
 400
 401 Support for ispell
 402 ==================
 403
 404 * `ispell` may skip certain things
 405
 406   * Using `ispell-skip-region-alist`
 407
 408     * ``Code`` should be skipped
 409
 410     * Literal text after ``::`` should be skipped
 411
 412   * A customization should switch this on so users are not surprised
 413
 414 Marriage with `forms-mode`
 415 ==========================
 416
 417 * Like I married `forms-mode` with `sdf-mode`
 418
 419 * Would allow editing a number of records with a fixed layout
 420
 421 * The base reStructuredText file should be either
 422
 423   * a list consisting of field lists
 424
 425     * The separator needs to be defined, however
 426
 427     * A section header or transition may be a useful separator
 428
 429   * a `list-table`
 430
 431   * a CSV file
 432
 433     * That would call for a general support for CSV support for forms
 434
 435     * May be `orgtbl-to-csv` in `org/org-table.el` could be useful for
 436       this
 437
 438 Marriage with `org-mode`
 439 ========================
 440
 441 * May be Org mode can be utilized instead of `forms-mode`
 442
 443   * See `orgtbl-mode`
 444
 445   * See `orgstruct-mode`
 446
 447     * Though this looks more like `allout-mode`
 448
 449 Intelligent quote insertion
 450 ===========================
 451
 452 * Use or develop something like `insert-pair`
 453
 454   * Main use for forgotten quoting
 455
 456     * Thus may rather quote preceding word than following one
 457
 458   * If `forward-sexp` could be overridden `insert-pair` might me
 459     usable directly
 460
 461 * Also add something like `delete-pair`
 462
 463 Sophisticated alignment
 464 =======================
 465
 466 * May be aligning can be used to get results like this
 467
 468   :Some:             Field
 469
 470   :Longer name:      Aligned
 471
 472   :Even longer name: More aligned
 473
 474   * See `align.el`
 475
 476 toc-mode per buffer
 477 ===================
 478
 479 * At the moment there can only be globally one TOC
 480
 481   * A TOC could be separate for each buffer
 482
 483 toc-mode could generate reST
 484 ============================
 485
 486 * The format of the generated TOC could be reStructuredText
 487
 488   * For instance as a bullet list
 489
 490   * So it could be copied and basted into a reStructuredText document
 491
 492   * Conversion could be done in toc-mode buffer
 493
 494 * An alternative could be that `rst-bullet-list-region` handles
 495   indented text properly
 496
 497 Improvements for comments
 498 =========================
 499
 500 * `comment-use-syntax` should be set to nil locally
 501
 502 * `comment-forward` should work so `comment-dwim` recognizes a
 503   commented region
 504
 505   * Then it could uncomment it automatically and use of prefix
 506     argument is no longer neccessary
 507
 508 Context sensitive M-q
 509 =====================
 510
 511 * M-q / `fill-paragraph` should check whether point is in section
 512   header and call `rst-adjust` in this case
 513
 514   * This would unify handling of changes in section headers and normal
 515     paragraphs
 516
 517 Switch to using `cl-lib`
 518 ========================
 519
 520 * Options to use `cl-lib`
 521
 522     There are various options, and you'll have to judge for yourself which
 523     is best for your particular case:
 524     - live with the warnings.
 525     - switch to cl-lib and ask users of older Emacsen to install cl-lib
 526       (available in GNU ELPA).
 527     - add things like (unless (fboundp 'cl-letf) (defalias 'cl-letf 'letf)).
 528     - change the code to use something else (e.g. for flet, you can switch
 529       to using either defadvice or (let ((f1 (lambda ..))) ...).
 530     - ...
 531
 532     -- Stefan Monnier
 533
 534 * Remove own implementations then
 535
 536 Filling of section headers
 537 ==========================
 538
 539 * Filling should recognize section headers and adjust the adornment
 540
 541   * Then a fill operation for a region wouldn't break the section
 542     header adornment
 543
 544   * In addition a fill operation could be used instead of adjusting a
 545     section header
 546
 547 Cursor after adjusting adornment
 548 ================================
 549
 550 * Adjusting a section header should move the cursor to the end of the
 551   adornment
 552
 553   * Then a following C-j / Return opens a new line instead of breaking
 554     the adornment just created
 555
 556 Copying literal blocks
 557 ======================
 558
 559 * Copying literal blocks should eat up the block indentation
 560
 561   * This way code fragments can be copied without removing the block
 562     indentation by hand
 563
 564 Structural operations for toc-mode
 565 ==================================
 566
 567 * Structrual operations for toc-mode
 568
 569   * Raise or lower sections
 570
 571   * Move sections around
 572
 573 Inhibit auto-fill in literal blocks
 574 ===================================
 575
 576 * In a literal block a space should not do auto-fill
 577
 578   * May be variable `normal-auto-fill-function` can be set mode
 579     specific
 580
 581     * Is normally `do-auto-fill`
 582
 583 toc-mode should leave mark
 584 ==========================
 585
 586 * When you jump to a different point in the document by using toc-mode
 587   the mark should be set at the point of departure
 588
 589   * This aligns with the semantic of other far jumps in the document
 590     such as `beginning-of-buffer`
 591
 592 Remembering last location per section
 593 =====================================
 594
 595 * Remembering the last location per section would make it possible to
 596   jump back to this location
 597
 598   * This is useful if several sections are worked on in parallel
 599
 600 * The jump into the section could happen from toc-mode
 601
 602   * Instead of to the section header
 603
 604   * May be by a special key
 605
 606 * Other section based jump commands could do similar
 607
 608   * For instance navigating by sections
 609
 610 * This calls for a general modifier for jumps
 611
 612 Multiple steps for `rst-adjust`
 613 ===============================
 614
 615 * Sometimes it's useful to adjust more than one step in the given
 616   direction
 617
 618   * For instance to follow a 2= title by 1= normal header skipping the
 619     usual 2- level
 620
 621 * Therefore using a counter may be useful
 622
 623 Enhance compilation support
 624 ===========================
 625
 626 * Compilation to ODT should be supported
 627
 628 * Arbitrary compilations should be supported using customization
 629
 630   * Key must be configurable
 631
 632   * Command must be configurable
 633
 634 * May be the whole toolset stuff needs to be replaced?
 635
 636 Support for longlines mode
 637 ==========================
 638
 639 * `longlines-mode` should use correct indentation for broken lines
 640
 641   * This is actually an enhancement of `longlines-mode`
 642
 643   * `longlines-mode` modifies the buffer
 644
 645     * This is needed to use all the standard functionality like
 646       `move-to-column`
 647
 648     * Using property `display` for inserting indentation does not work
 649       properly because of this
 650
 651   * Indentation must be inserted in the buffer
 652
 653     * However, it needs to have the property `intangible` so it can
 654       not be modified
 655
 656       * See `Emacs Lisp => 32.19 Text Properties => Special
 657         Properties`
 658
 659     * It would be nice to also have a visible indication for being
 660       automatic insertion
 661
 662   * Such indentation must be removed by `longlines-encode-*`
 663
 664     * Probably it should be marked by a special property such as
 665       `longlines-indentation`
 666
 667   * `longlines-wrap-line` needs a hook called after replacing the
 668     blank by a soft newline
 669
 670   * May be `longlines-*search-*` needs to be adapted as well?