3

In all of my source files, in whatever language, I use some trick or other to end compilation and then add a documentation trailer in perldoc format from which I can generate a man page. I always keep my manpages inside the source file to which they document.

I've thus far not found a means of doing this for Emacs Lisp. I've hundreds of source files in various languages in this format, so one way or the other I will bend eLisp to do my bidding :-)

Example from an ObjC file:

@end

/*==========================================================================*/
/*                         POD DOCUMENTATION                                */
/*==========================================================================*/
/* You may extract and format the documention section with the 'perldoc' cmd.

=head1 NAME

For Lisp I can obviously change the comment block to use ;;, but I do not have anything like the @end in ObjC, or the block comment in many languages or specialized hacks in various other languages.

How do I do it?

2
  • Please post your question about logging in to StackExchange separately, perhaps at the Meta StackExchange site (not on the Emacs StackExchange site). Thx.
    – Drew
    Dec 16, 2022 at 20:22
  • I have found one hack to do this although it does have an unwelcome side effect. If I place a quote in column 0 before the tail block and close the quote after the tail block I get my perldoc manpage section capability back. The down side is that I have to go through that documentation and add backslashes to any quotes in the documentation and those will show up in the resulting man page.
    – Dale Amon
    Dec 19, 2022 at 19:22

1 Answer 1

0

Sadly, unlike Common Lisp, elisp has no facility for defining new reader macros. If it did, it would be quite simple to add one which discards the rest of the file. That just leaves you with the possibility of modifying Emacs itself.

The code you want is in the function read0 in lread.c. There’s a whole switch there for things starting with #, which is the customary place to put such macros. You can see for example where it handles a non–lisp form such as the hash–bang at the start of a file on line 3905. You would do almost exactly the same thing, except you would read to the end of the file. I dunno what character you would pick; most of them are in use already.

2
  • Might be worth a look. Thanks.
    – Dale Amon
    Dec 24, 2022 at 0:44
  • You’re welcome.
    – db48x
    Dec 24, 2022 at 19:21

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.