[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: docstrings and elisp reference
From: |
Jean-Christophe Helary |
Subject: |
Re: docstrings and elisp reference |
Date: |
Thu, 8 Jun 2017 12:48:19 +0900 |
It was really not my intent to raise the temperature of this list to that
level. Apologies for that. But the discussion is really interesting.
1) I'll read the Doc Strings and Manuals in the GNU Coding Standards.
2) my remark about javadoc was not intended to suggest a replacement of the
current documentation, but to have a document that has all the docstring
information (Emacs API) in one place. It would be an alternative to the info
system, with exactly the same contents. It would be a great tool to find API
information and also very practical to check if the rules defined in the GNU
Coding Standards are respected.
3) my remark about duplication was full answered in the discussion and I'll
have even better insights when I complete 1) above. So I'll just put that aside
for the moment. My perspective was not exclusively l10n but also ease of access
to information for beginners, etc.
4) regarding "semantic support" (although I'm not 100% sure what Etienne is
referring to here) it seems to me that there are a number of not so hard things
to do on the (some ?) texi conversion templates. I've been working on a CSS for
the manuals and I found the HTML conversion templates remarkably underused (I'm
currently discussing this on address@hidden). Even while maintaining legacy
HTML support, there are plenty of areas where CSS selectors could be added to
considerably enhance the output. There are even some regressions, for ex, the
4.8 version I was unknowingly working with until this morning added a
class="defun" to definitions, and that class information is gone in 6.3
(replaced by a generic <dl> tag).
I understand I'm going in a lot of directions at the moment, sorry for that.
Jean-Christophe
> Jun 8, 2017 11:29、Etienne Prud’homme <address@hidden>のメール:
>
> Drew Adams <address@hidden> writes:
>
>> And this is not JavaDoc. The Elisp manual is not purely
>> and simply an API reference manual.
>
> It’s worth mentioning that JavaDoc documentation style is particularly
> useful for Object-Oriented Programming and strongly typed languages. I
> think it’s even mandatory with OOP to be readable.
>
> However, I also think Jean-Christophe makes a good point about
> documentation generation. Not with duplication, but semantic support.
> While documentation support is awesome in Emacs with GNU libraries, it’s
> not always so with third-party documentation tools. I’m thinking about
> Zeal (and to a very limited extent Dash that is not free).
>
> Those tools are highly effective for semantic indexation for newcomers
> since they offer a simple interface for hundred FLOSS libraries. GNU
> projects are almost nonexistent.
>
> I’ve been trying in the past to port GNU projects documentation and I
> finally gave up. I find Texinfo to be very limited when it comes to
> semantic support. It’s really hard to extract meaningful definitions
> from texi files.
>
- docstrings and elisp reference, Jean-Christophe Helary, 2017/06/05
- Re: docstrings and elisp reference, Tino Calancha, 2017/06/05
- Re: docstrings and elisp reference, Jean-Christophe Helary, 2017/06/06
- Re: docstrings and elisp reference, Eli Zaretskii, 2017/06/06
- Re: docstrings and elisp reference, Stephen Leake, 2017/06/06
- RE: docstrings and elisp reference, Drew Adams, 2017/06/06
- Re: docstrings and elisp reference, Etienne Prud’homme, 2017/06/07
- Re: docstrings and elisp reference,
Jean-Christophe Helary <=
- Re: docstrings and elisp reference, Chad Brown, 2017/06/08
- Re: docstrings and elisp reference, Jean-Christophe Helary, 2017/06/08
- Re: docstrings and elisp reference, Eli Zaretskii, 2017/06/08
- Re: docstrings and elisp reference, Jean-Christophe Helary, 2017/06/08
- Re: docstrings and elisp reference, Chad Brown, 2017/06/08
- Re: docstrings and elisp reference, Etienne Prud’homme, 2017/06/08
- Re: docstrings and elisp reference, Richard Stallman, 2017/06/09
- Re: docstrings and elisp reference, Eli Zaretskii, 2017/06/08
- Re: docstrings and elisp reference, Etienne Prud’homme, 2017/06/08
- Re: docstrings and elisp reference, Eli Zaretskii, 2017/06/08