From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Emanuel Berg Newsgroups: gmane.emacs.help Subject: Re: Emacs Mini Manual (PART 3) - CUSTOMIZING AND EXTENDING EMACS Date: Sat, 12 Jul 2014 21:49:03 +0200 Organization: Aioe.org NNTP Server Message-ID: <87ha2mici8.fsf@debian.uxu> References: <5eaf0440-3124-4d89-bd20-ddada9a3db12@googlegroups.com> <87r425qi4t.fsf@debian.uxu> <619ae998-2ce5-428d-bec7-a654427b81d0@googlegroups.com> <87k37nzy2q.fsf@debian.uxu> <87ion71r98.fsf@debian.uxu> <87bnswyi4u.fsf@debian.uxu> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain X-Trace: ger.gmane.org 1405194625 31831 80.91.229.3 (12 Jul 2014 19:50:25 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sat, 12 Jul 2014 19:50:25 +0000 (UTC) To: help-gnu-emacs@gnu.org Original-X-From: help-gnu-emacs-bounces+geh-help-gnu-emacs=m.gmane.org@gnu.org Sat Jul 12 21:50:18 2014 Return-path: Envelope-to: geh-help-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1X63JK-00020y-Ae for geh-help-gnu-emacs@m.gmane.org; Sat, 12 Jul 2014 21:50:18 +0200 Original-Received: from localhost ([::1]:50171 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1X63JJ-0007F9-S4 for geh-help-gnu-emacs@m.gmane.org; Sat, 12 Jul 2014 15:50:17 -0400 Original-Path: usenet.stanford.edu!news.tele.dk!news.tele.dk!small.news.tele.dk!newsfeed.xs4all.nl!newsfeed4a.news.xs4all.nl!xs4all!news.stack.nl!aioe.org!.POSTED!not-for-mail Original-Newsgroups: gnu.emacs.help Original-Lines: 62 Original-NNTP-Posting-Host: SIvZRMPqRkkTHAHL6NkRuw.user.speranza.aioe.org Original-X-Complaints-To: abuse@aioe.org User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/24.3 (gnu/linux) X-Notice: Filtered by postfilter v. 0.8.2 Cancel-Lock: sha1:ocrVu6PjCoTzfdqQd9IvjZC5maw= Mail-Copies-To: never Original-Xref: usenet.stanford.edu gnu.emacs.help:206389 X-BeenThere: help-gnu-emacs@gnu.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: Users list for the GNU Emacs text editor List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: help-gnu-emacs-bounces+geh-help-gnu-emacs=m.gmane.org@gnu.org Original-Sender: help-gnu-emacs-bounces+geh-help-gnu-emacs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.help:98661 Archived-At: Javier writes: >> Yes, documentation on-screen is great in the man >> page sense, the online Emacs help sense, when you >> want to know some part of the interface. If you do >> Elisp for some time, and then switch to C, you feel >> like an idiot having to Google stuff because the >> interface isn't available (though some of the C is >> in the manpages). But there is actually nothing that >> stops anyone from writing C (interface) >> documentation that would work more or less like the >> Elisp one. > > It would be an interesting project to convert those > documents to texinfo format. With Python it is > possible to convert the documentation (sphinx doc > generator) of Python and its libraries to texinfo, > and documentation can be gerated automatically for > any python project to texinfo. Yeah? What documents? You can get the Emacs manual in texinfo here: http://www.gnu.org/software/emacs/manual/texi/emacs.texi.tar.gz I take it that's what you get with the info command, only not markuped, of course. In the the on-line help, the docstrings associated to defuns and variables, they aren't that advanced. The arguments should be mentioned, in caps - probably to make them visible - they get the `help-argument-name' face. In the source, it looks kind of strange with arguments not the same case in the docstring as everywhere else. But in help-mode the parameters in the definition gets uppercased, so there it's consistent. All parameters should be mentioned, in the docstring, and there should be two spaces after a full stop. This is something I learned from `checkdoc-current-buffer', check out this example - it should tell you arg2 isn't mentioned (apart from some other library related stuff that doesn't apply). But in reality far from everything is documented and sometimes it is, but not the parameters... (defun test-param-doc (arg1 arg2) "ARG1 does this. Also check out `find-file'." (interactive) nil) ; eval here (checkdoc-current-buffer t) ; and here Some hypertext is possible with `this' method - if there actually is such a function or whatever, that get hypertexted and the `button' face in help-mode. -- underground experts united