Add latex key to configure literal blocks caption position in PDF output

[jfbu]

With literalblockcappos=b added to 'sphinxsetup', the captions of literal blocks are typeset after the literal block in PDF output. Default is t which says to typeset them above.

Also added verbatimcontinuedalign and verbatimcontinuesalign with possible values l, c, r for alignment of continuation hints with respect to literal block contents (relates #3792). This gives for example:

The verbatimhintsturnover default is now true so that at 1.7 continuation hints (internationalized) will be the default.

Details

• In case the caption is printed after the literal block, nevertheless the internal links will be set up to point to start of literal block.

• The caption width is now wrapped to the same maximal width as for table captions: the \LTcapwidth parameter whose default is 4in.

• I have considered horizontal alignment of the caption itself. This can be done indeed for literal blocks, but I dropped it because it is not easy to do the similar thing for tables:

  • for longtable, one can patch macros for alignment with respect to the table sides, but not easily alignment with respect to the line width,
  • for tabular, tabulary, one can extend caption macro to get alignment with respect to the line width, but not with respect to the table sides (as we dropped threeparttable which could be used for that but has many induced problems) except if the table width is known in advance.

  Hence I dropped horizontal alignment for caption of literal blocks.

• In future, if a global config setting is added for caption placement, this PR does it already for literal blocks, so this will facilitate implementation. For tables, it is already not too complicated thanks to the templates. For figures, some refactoring is needed first.

• The \sphinxcaption which is used for tables (except longtable) and with this PR for literal blocks too has been made more flexible: earlier it hard-coded reset of \abovecaptionskip/\belowcaptionskip to 0pt for uniform treatement of tables, now the two are reset to values given by some user modifiable macros.

• If caption is on top the distance from baseline of caption text to frame of literal block is now same value as for table captions (\sphinxbelowcaptionspace whose default is 6pt = 0.5\baselineskip = \parskip). This is slightly increase from previous setting, in order to get uniformity with table caption placement.

• More generally, the vertical spacing for literal blocks is now customizable via renewcommand of latex macros (see next).

Memo on vertical spacing

Here are the default values for vertical spacing (in English documents):

• tables:

  • if the table has no caption, there is \baselineskip (12pt) + \parskip (6pt) + \sphinxtablepre (0pt) = 18pt from baseline of text to top of table,
  • if the table has a caption, this is again 18pt to top of caption (i.e. \ht\strutbox = 8.4pt above caption text baseline),
  • underneath table there is 12pt+6pt+\sphinxtablepost(=\medskipamount=6pt) = 24pt from table bottom frame to next text baseline.

• literal blocks:

  • if with no caption, there is \sphinxverbatimsmallskipamount (=\smallskipamount=3pt) + \baselineskip (12pt) - \FrameHeightAdjust (default 6pt) = 9pt from baseline of previous text to top of block frame,
  • if with caption (on top), there is \abovecaptionskip (10pt) + same (12 pt - 6pt) = 16pt from baseline of previous text to top of caption,
  • after the literal-block there is \baselineskip+\parskip=18pt from bottom frame to next text baseline.

These values were already the ones theoretically for literal blocks before this PR, but for a reason I have not fully understood, in case with caption I measured a bit smaller on stable branch, perhaps 15pt, not the 16pt. Perhaps some stretch-shrink which is now not rendered due to refactoring of latex macros.

Compared to tables, literal blocks are less separated from ambient text, and in cse of caption there is much less difference between "before" and "after" spaces.

Note: all this is now customizable easily except the spacing after literal block, there is no hook to customize it, contrarily to tables. This can be added later if a need arises.

(regarding literal block top vertical spacing, it was reduced in #2460)

Relates

#3792, #2460, #3504

and #1723

[tk0miya]

This might be related with #1723. But the proper way is not discussed yet. So let's go ahead.

[jfbu]

Indeed, this PR partially addresses #1723 but only for code-blocks and only for PDF output. It is thus not complete feature.

thanks for review, now merging, I am online for a few days.