autodoc: Rework calculating the usage sections

[khwilliamson]

Entries in perlapi and perlintern end with a usage section that give the calling prototype signatures of the items in the entry. This commit reworks the calculation of that. Future planned commits were running into limitations with the previous algorithm. This new one makes those commits easier, is hopefully clearer, and it turns out fixes some bugs where the signatures extended too far right in the verbatim blocks.

[jkeenan]

When I build first blead, and then your branch, and look at the respective pod/perlapi.pod outputs, I get this (diff -w):

$ cat gh-22345.pod.perlapi.pod.diff 
3881,3886d3880
< =over 3
< 
<    END_EXTERN_C
< 
< =back
< 
4085,4090d4078
< =over 3
< 
<    START_EXTERN_C
< 
< =back
< 
4882,4883c4870,4871
<  COPHH *  cophh_delete_pv (COPHH *cophh, const char *key, U32 hash,
<                            U32 flags)
---
>  COPHH *  cophh_delete_pv (COPHH *cophh, const char *key,
>                            U32 hash, U32 flags)
11731,11732c11719,11722
<  GV *  gv_fetchsv       (SV *name, I32 flags, const svtype sv_type)
<  GV *  gv_fetchsv_nomg  (SV *name, I32 flags, const svtype sv_type)
---
>  GV *  gv_fetchsv       (SV *name, I32 flags,
>                          const svtype sv_type)
>  GV *  gv_fetchsv_nomg  (SV *name, I32 flags,
>                          const svtype sv_type)
11827,11828c11817,11818
<  void  gv_init_pvn(GV *gv, HV *stash, const char *name, STRLEN len,
<                    U32 flags)
---
>  void  gv_init_pvn(GV *gv, HV *stash, const char *name,
>                    STRLEN len, U32 flags)
13892c13882,13883
<  PerlIO *   PerlIO_open        (const char *path, const char *mode)
---
>  PerlIO *   PerlIO_open        (const char *path,
>                                 const char *mode)
13899,13900c13890,13891
<  PerlIO *   PerlIO_reopen      (const char *path, const char *mode,
<                                 PerlIO *old)
---
>  PerlIO *   PerlIO_reopen      (const char *path,
>                                 const char *mode, PerlIO *old)
14054c14045,14046
<  void  repeatcpy(char *to, const char *from, SSize_t len, IV count)
---
>  void  repeatcpy(char *to, const char *from, SSize_t len,
>                  IV count)
30180c30172,30173
<  I32  sv_cmp_flags(SV * const sv1, SV * const sv2, const U32 flags)
---
>  I32  sv_cmp_flags(SV * const sv1, SV * const sv2,
>                    const U32 flags)
30922c30915,30916
<                        const STRLEN len, const char * const little,
---
>                        const STRLEN len,
>                        const char * const little,
31476,31477c31470,31471
<  MAGIC *  sv_magicext(SV * const sv, SV * const obj, const int how,
<                       const MGVTBL * const vtbl,
---
>  MAGIC *  sv_magicext(SV * const sv, SV * const obj,
>                       const int how, const MGVTBL * const vtbl,
34385,34387c34379,34382
<  STRLEN  sv_utf8_upgrade_flags     (SV * const sv, const I32 flags)
<  STRLEN  sv_utf8_upgrade_flags_grow(SV * const sv, const I32 flags,
<                                     STRLEN extra)
---
>  STRLEN  sv_utf8_upgrade_flags     (SV * const sv,
>                                     const I32 flags)
>  STRLEN  sv_utf8_upgrade_flags_grow(SV * const sv,
>                                     const I32 flags, STRLEN extra)
36313c36308,36309
<                                const U8 * const e, const U32 flags)
---
>                                const U8 * const e,
>                                const U32 flags)
36372c36368,36369
<                                          STRLEN len, const U8 **ep,
---
>                                          STRLEN len,
>                                          const U8 **ep,
36461,36462c36458,36459
<  bool  is_utf8_invariant_string_loc(const U8 * const s, STRLEN len,
<                                     const U8 **ep)
---
>  bool  is_utf8_invariant_string_loc(const U8 * const s,
>                                     STRLEN len, const U8 **ep)
37944c37941,37942
<  UV  utf8_to_uvchr_buf(const U8 *s, const U8 *send, STRLEN *retlen)
---
>  UV  utf8_to_uvchr_buf(const U8 *s, const U8 *send,
>                        STRLEN *retlen)
38269c38267,38268
<                        NN const char *what, NN const char *op_name)
---
>                        NN const char *what,
>                        NN const char *op_name)

Is that what you were expecting?

[khwilliamson]

Yes.

Entries are supposed to use only the first 78 columns. This is because we strive to avoid ugly wrapping in windows at least 80 characters wide, and common pagers (like less) reserve up to two columns for their own use.

If you look at the entries that are folded differently, the previous version occupied 79 columns

The pod isn't supposed to include trivial prototype lines consisting solely of the name of the construct. The previous version wrongly included the EXTERN_C lines, therefore