bug#20780: 25.0.50; explain where to find skeletons in autotype info manual

bug#20780: 25.0.50; explain where to find skeletons in autotype info manual

[Nicolas Richard]

I was trying to find a template/skeleton mechanism, and that leads to
(info "(emacs) Text") :
>    The “automatic typing” features may be useful when writing text.
> *note The Autotype Manual: (autotype)Top.

Following through to the autotype info page, I'm a bit disappointed
because the manual explains how skeletons can:
- accept input in section 1,
- be modified with prefix arguments in section 2,
- be called as abbrevs in section 3,
and we have to wait section 4 to read about a (quite scary,
IMO) way to define skeletons. I'm now convinced that it is in fact not
expected that the *user* writes her own skeletons. Is that right ?

If that is the case, I suggest to mention that fact right from the
beginning, and maybe explicitly list a few places where skeletons are
actually availables (which key). C-mode is mentionned but from "emacs -Q
-f c-mode" I couldn't find anything in the menu.

Nicolas.

bug#20780: 25.0.50; explain where to find skeletons in autotype info manual

[Lars Ingebrigtsen]

Nicolas Richard <youngfrog@members.fsf.org> writes:

> I was trying to find a template/skeleton mechanism, and that leads to
> (info "(emacs) Text") :
>>    The “automatic typing” features may be useful when writing text.
>> *note The Autotype Manual: (autotype)Top.
>
> Following through to the autotype info page, I'm a bit disappointed
> because the manual explains how skeletons can:
> - accept input in section 1,
> - be modified with prefix arguments in section 2,
> - be called as abbrevs in section 3,
> and we have to wait section 4 to read about a (quite scary,
> IMO) way to define skeletons. I'm now convinced that it is in fact not
> expected that the *user* writes her own skeletons. Is that right ?

I think that's right.

> If that is the case, I suggest to mention that fact right from the
> beginning, and maybe explicitly list a few places where skeletons are
> actually availables (which key). C-mode is mentionned but from "emacs -Q
> -f c-mode" I couldn't find anything in the menu.

I wonder why the autotype manual is linked from the Emacs manual at
all.  It's a very low-level (lispref-like) manual, and doesn't really
seem to be something we should steer users towards?

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#20780: 25.0.50; explain where to find skeletons in autotype info manual

[Eli Zaretskii]

> From: Lars Ingebrigtsen <larsi@gnus.org>
> Date: Wed, 09 Oct 2019 05:46:29 +0200
> Cc: 20780@debbugs.gnu.org
> 
> I wonder why the autotype manual is linked from the Emacs manual at
> all.  It's a very low-level (lispref-like) manual, and doesn't really
> seem to be something we should steer users towards?

AFAIR because some user-level feature(s) is/are described only there.
But I might be mistaken.

bug#20780: 25.0.50; explain where to find skeletons in autotype info manual

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Lars Ingebrigtsen <larsi@gnus.org>
>> Date: Wed, 09 Oct 2019 05:46:29 +0200
>> Cc: 20780@debbugs.gnu.org
>> 
>> I wonder why the autotype manual is linked from the Emacs manual at
>> all.  It's a very low-level (lispref-like) manual, and doesn't really
>> seem to be something we should steer users towards?
>
> AFAIR because some user-level feature(s) is/are described only there.
> But I might be mistaken.

You're right; I didn't look closely enough.  Basically the least
user-friendly bit is the "Skeleton Language" node -- the rest are more
or less something users can be expected to relate to.

Would it make sense to just move that node to after the more user-facing
nodes?

@menu
* Using Skeletons::        How to insert a skeleton into your text.
* Wrapping Skeletons::     Putting existing text within a skeleton.
* Skeletons as Abbrevs::   An alternative for issuing skeleton commands.
* Skeleton Language::      Making skeleton commands insert what you want.
* Inserting Pairs::        Typing one character and getting another
                             after point.
* Autoinserting::          Filling up empty files as soon as you visit them.
* Copyrights::             Inserting and updating copyrights.
* Executables::            Turning interpreter scripts into executables.
* Timestamps::             Updating dates and times in modified files.
* QuickURL::               Inserting URLs based on text at point.
* Tempo::                  Flexible template insertion.
* Hippie Expand::          Expansion of text trying various methods.


[...]

@end menu


-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#20780: 25.0.50; explain where to find skeletons in autotype info manual

[Eli Zaretskii]

> From: Lars Ingebrigtsen <larsi@gnus.org>
> Cc: youngfrog@members.fsf.org,  20780@debbugs.gnu.org
> Date: Wed, 09 Oct 2019 19:44:07 +0200
> 
> > AFAIR because some user-level feature(s) is/are described only there.
> > But I might be mistaken.
> 
> You're right; I didn't look closely enough.  Basically the least
> user-friendly bit is the "Skeleton Language" node -- the rest are more
> or less something users can be expected to relate to.
> 
> Would it make sense to just move that node to after the more user-facing
> nodes?

Fine with me, thanks.

bug#20780: 25.0.50; explain where to find skeletons in autotype info manual

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

> Fine with me, thanks.

OK; done, and I'm closing this bug report.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#20780: 25.0.50; explain where to find skeletons in autotype info manual

[Nicolas Richard via Bug reports for GNU Emacs, the Swiss army knife of text editors]

On 09/10/19 20:08, Lars Ingebrigtsen wrote:
> Eli Zaretskii <eliz@gnu.org> writes:
> 
>> Fine with me, thanks.
> 
> OK; done, and I'm closing this bug report.

Thanks for taking care of this bug report.

FWIW I had not looked any further into skeletons since I wrote the bug
report, and I still have no clue on how to use them. I thought I'd give
it another try just now:

at (info "(autotype) Skeletons as Abbrevs") I found:
>    Say you want ???ifst??? to be an abbreviation for the C language if
> statement.  You will tell Emacs that ???ifst??? expands to the empty string
> and then calls the skeleton command.  In Emacs Lisp you can say
> something like ???(define-abbrev c-mode-abbrev-table "ifst" "" 'c-if)???.

I tried to run that piece of lisp, then typed ifst in a test.c file, and
all I got was an error (void-function c-if)

I do understand that c-if is not defined as a function, but is it
expected that *I* write it ? I was hoping it would just work out of the box.

I still think we should mention some workings examples in the manual,
near the beginning of it.

Now I'm grepping for '(define-skeleton' in the git repo.
It returns results in sh-script.el, modula2.el, python.el and a few
others. Could any of those be mentionned in section 1 ? e.g. in
shell-script-mode, C-c C-c runs sh-case, which is a skeleton. I think
it's a great example of all the things mentionned in section 1.

thanks,

-- 
Nicolas.

bug#20780: 25.0.50; explain where to find skeletons in autotype info manual

[Lars Ingebrigtsen]

Nicolas Richard <theonewiththeevillook@yahoo.fr> writes:

> I still think we should mention some workings examples in the manual,
> near the beginning of it.
>
> Now I'm grepping for '(define-skeleton' in the git repo.
> It returns results in sh-script.el, modula2.el, python.el and a few
> others. Could any of those be mentionned in section 1 ? e.g. in
> shell-script-mode, C-c C-c runs sh-case, which is a skeleton. I think
> it's a great example of all the things mentionned in section 1.

I think adding an example to the manual would be great, but I'm not sure
which.  The one you mention seems a bit excessive for the manual...

(define-skeleton sh-case
  "Insert a case/switch statement.  See `sh-feature'."
  (csh "expression: "
       "switch( " str " )" \n
       > "case " (read-string "pattern: ") ?: \n
       > _ \n
       "breaksw" \n
       ( "other pattern, %s: "
	 < "case " str ?: \n
	 > _ \n
	 "breaksw" \n)
       < "default:" \n
       > _ \n
       resume:
       < < "endsw" \n)
  (es)
  (rc "expression: "
      > "switch( " str " ) {" \n
      > "case " (read-string "pattern: ") \n
      > _ \n
      ( "other pattern, %s: "
	"case " str > \n
	> _ \n)
      "case *" > \n
      > _ \n
      resume:
      ?\} > \n)
  (sh "expression: "
      > "case " str " in" \n
      ( "pattern, %s: "
	> str sh-non-closing-paren \n
	> _ \n
	";;" \n)
      > "*" sh-non-closing-paren \n
      > _ \n
      resume:
      "esac" > \n))

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no