On Wed, Feb 15, 2012 at 5:29 AM, Robert Klemme
<shortcutter / googlemail.com> wrote:
> On Wed, Feb 15, 2012 at 3:08 AM, Kevin <darkintent / gmail.com> wrote:
>
>> I remember saying in one of these threads that documentation should be
>> pervasive and this is a perfect example of why this should be the
>> case. The syntax rules of any language, natural or constructed,
>> belongs in the standard documentation of said language. The only
>> reason this wasn't really done in the past is that a printed book
>> couldn't contain this information in a reasonable way.
>
> What exactly is your definition of "reasonable"? According to my
> definition a book is perfectly capable of providing documentation of
> syntax in a reasonable way - and actually there are tons of books
> around which present syntax of languages in a way useful for the
> reader.
>
>> Hypertext allows us to achieve this.
>
> Of course you can also document formal language syntax in a hypertext
> document, and maybe even better than in a printed book. It is not
> necessary though.
>
> Kind regards
>
> robert
>
>
> --
> remember.guy do |as, often| as.you_can - without end
> http://blog.rubybestpractices.com/
>

By reasonable I mean that the volume would not become overly large and
cumbersome to navigate.  Containing a proper treatment of the entire
grammar of most languages would be about the same size as a good
pocket or abridged dictionary.  Then there is all the flipping around
between pages which doesn't help concentration.  In the context of
constructed languages like Ruby one may well be literate but not be
familiar with all of the different parts of the syntax. A language
doesn't exist without the grammar and the API.  Technical limitations
have prevented us from representing this fact for most of human
history, instead we've tried to club the entire grammar of our
languages into our heads with some success. That doesn't mean we
should keep doing that when we have the tools to avoid it.  Imagine if
we tried to include the entire source for the whole standard library
in the pickaxe the book would be huge and a true pain to navigate.
This annoyance is of course lessened in the electronic versions
because you get links you can click to quickly navigate from the index
at least and you usually have some capacity to do a find for a
specific word etc. Emacs got the right idea, even if the format used
isn't as nice as hypertext.  The main things I would add are a
function that could tell me what a given function is made of*, and
integration with the elisp manual.  That would complement the fact
that describe-function defaults to selecting the function at the
current depth.**



I've been getting better and better at reading code as I go deeper
into programming, but I still long for better and more easily
navigable documentation.
*Eg. Move into an Emacs function fire off command that shows the
various parts of a function and links to relevant sections of the
manual that explain those things.  Though I don't think that is
technically possible.
**If you have code like (let ((f b))) if you put the cursor within the
level of (let) describe-function will have let already selected.