Re: libnettle/libhogweed WIP

[Eli Zaretskii <eliz@gnu.org>]

> From: Ted Zlatanov <tzz@lifelogs.com>
> Date: Thu, 20 Apr 2017 16:24:33 -0400
> 
> Incidentally it would be nice if NEWS (Outline mode) supported clickable
> links to the manuals like "(elisp) Formatting Strings" or
> (info "(elisp) Formatting Strings") or something else. Right now it's a
> bit awkward.

Patches to add that are welcome, I think.

> EZ> Something like this at the beginning of the node:
> 
> EZ>   All of the functions described here accept argument lists of the
> EZ>   form @code{(BUFFER-OR-STRING START END CODING-SYSTEM NOERROR)},
> EZ>   where BUFFER-OR-STRING ...
> 
> OK, but I want to link to that from the C function docs too, since they
> also will reference that format. Would I link to the manual node? Is
> that OK for C functions, which are kind of standalone as far as docs go?

If you mean primitives implemented in C that are exposed to Lisp,
yes.  For internal C functions inaccessible from Lisp, just describe
that in a comment preceding the functions.

> I think I mentioned already that I am also considering how to specify
> the *output* of these functions better. It feels like it should parallel
> the same BUFFER-OR-STRING-OR-FILE structure so the functions can write
> to the desired place with minimal unintended visibility from Lisp.

I think both this and the other sub-thread arrived at a point where it
is important to present a list of use cases we envision and would like
to support, because these kinds of decisions are prone to errors if we
don't hold the use cases in our minds.

So could you please present such a list, describing the source of the
text to be encrypted/decrypted/hashed, the purpose of the operation
(i.e. some higher-level context), and the destination where the
encrypted/decrypted/hashed text will go?  The list doesn't have to be
exhaustive, but it should include the most important use cases.

Thanks.