Eliminating etc/DOC - formatting multiline strings

[Stefan Kangas]

I've been looking a little bit at how we could rid of etc/DOC, as per
this item in TODO:

    ** Eliminate the etc/DOC file altogether
    We could try and eliminate the DOC file altogether.  See
    https://lists.gnu.org/r/emacs-devel/2021-05/msg00237.html

I'm not sure what exactly are our goals here.  If it just to get rid of
the external file, and store the strings in a special memory segment,
then we could change make-docfile.c to generate a .h file instead.  This
looks doable to me.

If, however, we _also_ want to get rid of the external file generation
and make-docfile.c completely (keeping only the globals.h part), just
relying on C, I'm not sure about one aspect:

How would we want to write docstrings given the lack of multiline
strings in C?

Consider this fragment:

    DEFUN ("map-keymap-internal", Fmap_keymap_internal, \
        Smap_keymap_internal, 2, 2, 0,
           doc: /* Call FUNCTION once for each event binding in KEYMAP.
    FUNCTION is called with two arguments: the event that is bound, and
    the definition it is bound to.  The event may be a character range.
    If KEYMAP has a parent, this function returns it without processing it.  */)

Thanks to using comments that make-docfile.c picks up later, we get away
with emulating a multiline string in this way.  If we would like to use
standard C strings, and eschew the external tool, AFAIU, we end up with
one of these instead:

1.  DEFUN ("map-keymap-internal", Fmap_keymap_internal, \
        Smap_keymap_internal, 2, 2, 0,
           "Call FUNCTION once for each event binding in KEYMAP.\n\
    FUNCTION is called with two arguments: the event that is bound, and\n\
    the definition it is bound to.  The event may be a character range.\n\
    If KEYMAP has a parent, this function returns it without processing it.")

2.  DEFUN ("map-keymap-internal", Fmap_keymap_internal, \
        Smap_keymap_internal, 2, 2, 0,
           "Call FUNCTION once for each event binding in KEYMAP.\n"
    "FUNCTION is called with two arguments: the event that is bound, and\n"
    "the definition it is bound to.  The event may be a character range.\n"
    "If KEYMAP has a parent, this function returns it without processing it."

Maybe we just can't get rid of using an external tool, if we don't want
docstrings to get quite cumbersome to write?  Or should we build special
tooling (e.g. a minor mode) to hide this aspect and take care of this
editing job transparently for us?  Won't that be brittle?  Or are we
perhaps happy to edit docstrings even if they look like they do above?
Am I missing something obvious?  Is doing this a win even?  And so on.

Thanks in advance for any comments.

PS. My apologies if this was already discussed; I couldn't find it in
    the archives.