include Ada Reference Manual info files in ada-mode ELPA package?

include Ada Reference Manual info files in ada-mode ELPA package?

[Stephen Leake]

I'm preparing the next release of the ada-mode ELPA package, and I'm
wondering whether to include the Ada Reference Manual (ARM) in info
format.

The ARM is the standard reference manual for the Ada language, which is
the language that ada-mode supports. So it is convenient to have the
info version available.

The ARM is available on the web in info
(http://stephe-leake.org/ada/arm.html) and other
(http://www.ada-auth.org/standards/ada12.html) formats. It is also
available as a Debian (and possibly other distribution) package.

So including the ARM in the ELPA package on some systems would be
redundant. 

Perhaps making the ARM a separate ELPA package would be the right
choice. It would be an info-only package, so there would be no .el file
to hold the meta-data header. I guess I'd have to add one just for that.
Would that be ok?

-- 
-- Stephe

Re: include Ada Reference Manual info files in ada-mode ELPA package?

[Stefan Monnier]

> So including the ARM in the ELPA package on some systems would be
> redundant. 
> Perhaps making the ARM a separate ELPA package would be the right
> choice.  It would be an info-only package, so there would be no .el file
> to hold the meta-data header. I guess I'd have to add one just for that.

Given its size and the fact that it's also distributed/installed
separately from Emacs, it's preferable not to include it in the ada-mode
package itself.

Instead the ada-mode package should ideally do its best to make use of
a pre-installed ARM (e.g. support for C-h S), of course.  Maybe we could
provide the ARM as an ELPA package, but I'm not completely sure how
important that would be.  Not sure about the copyright/licensing either
(apparently it counts as Free, so I think it'd be OK to include it (even
though we don't own the copyright), just like we include the Unicode
standard).


        Stefan

Re: include Ada Reference Manual info files in ada-mode ELPA package?

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

What license is it under?  We can't include documenation that isn't free.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: include Ada Reference Manual info files in ada-mode ELPA package?

[Stephen Leake]

Richard Stallman <rms@gnu.org> writes:

> [[[ To any NSA and FBI agents reading my email: please consider    ]]]
> [[[ whether defending the US Constitution against all enemies,     ]]]
> [[[ foreign or domestic, requires you to follow Snowden's example. ]]]
>
> What license is it under?  We can't include documenation that isn't free.

From the doc:

    This document may be copied, in whole or in part, in any form or by
    any means, as is or with alterations, provided that (1) alterations
    are clearly marked as alterations and (2) this copyright notice is
    included unmodified in any copy. Compiled copies of standard library
    units and examples need not contain this copyright notice so long as
    the notice is included in all copies of source code and
    documentation.

Debian judged it free, and allows it as a package.

-- 
-- Stephe

Re: include Ada Reference Manual info files in ada-mode ELPA package?

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

    This document may be copied, in whole or in part, in any form or by
    any means, as is or with alterations, provided that (1) alterations
    are clearly marked as alterations and (2) this copyright notice is
    included unmodified in any copy. Compiled copies of standard library
    units and examples need not contain this copyright notice so long as
    the notice is included in all copies of source code and
    documentation.


That is a free license, so we can distribute it.

Thus, there is only the practical question of what is most convenient.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: include Ada Reference Manual info files in ada-mode ELPA package?

[Stephen Leake]

Stephen Leake <stephen_leake@stephe-leake.org> writes:

> Perhaps making the ARM a separate ELPA package would be the right
> choice. It would be an info-only package, so there would be no .el file
> to hold the meta-data header. I guess I'd have to add one just for that.
> Would that be ok?

I tried this. It fails because `archive--metadata' in
elpa/admin/archive-contents.el thinks it's a simple (one-file) package,
because there is only one .el file. A simple fix is to also include
'dir' in that check. Here's a patch against ELPA head (also fixes a
small typo in an error message):

--- a/admin/archive-contents.el
+++ b/admin/archive-contents.el
@@ -167,7 +167,7 @@ EXTRAS is an alist with additional metadata.
 
 PKG is the name of the package and DIR is the directory where it is."
   (let* ((mainfile (expand-file-name (concat pkg ".el") dir))
-         (files (directory-files dir nil "\\.el\\'")))
+         (files (directory-files dir nil "^dir$\\|\\.el\\'")))
     (setq files (delete (concat pkg "-pkg.el") files))
     (setq files (delete (concat pkg "-autoloads.el") files))
     (cond
@@ -201,7 +201,7 @@ PKG is the name of the package and DIR is the directory where it is."
                   (list (cons :url url)
                         (cons :keywords keywords)))))))
      (t
-      (error "Can find main file %s file in %s" mainfile dir)))))
+      (error "Can't find main file %s file in %s" mainfile dir)))))
 
 (defun archive--process-simple-package (dir pkg vers desc req extras)
   "Deploy the contents of DIR into the archive as a simple package.


With that fix, the ada-ref-man package installs, and the info files show
up nicely.

Ok to install the patch in ELPA?

--
-- Stephe

Re: include Ada Reference Manual info files in ada-mode ELPA package?

[Andreas Schwab]

Stephen Leake <stephen_leake@stephe-leake.org> writes:

> --- a/admin/archive-contents.el
> +++ b/admin/archive-contents.el
> @@ -167,7 +167,7 @@ EXTRAS is an alist with additional metadata.
>  
>  PKG is the name of the package and DIR is the directory where it is."
>    (let* ((mainfile (expand-file-name (concat pkg ".el") dir))
> -         (files (directory-files dir nil "\\.el\\'")))
> +         (files (directory-files dir nil "^dir$\\|\\.el\\'")))

Please use \` and \' instead of ^ and $.

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Re: include Ada Reference Manual info files in ada-mode ELPA package?

[Stephen Leake]

Andreas Schwab <schwab@linux-m68k.org> writes:

> Stephen Leake <stephen_leake@stephe-leake.org> writes:
>
>> --- a/admin/archive-contents.el
>> +++ b/admin/archive-contents.el
>> @@ -167,7 +167,7 @@ EXTRAS is an alist with additional metadata.
>>  
>>  PKG is the name of the package and DIR is the directory where it is."
>>    (let* ((mainfile (expand-file-name (concat pkg ".el") dir))
>> -         (files (directory-files dir nil "\\.el\\'")))
>> +         (files (directory-files dir nil "^dir$\\|\\.el\\'")))
>
> Please use \` and \' instead of ^ and $.

What is the rationale for that? 

Is it documented somewhere? I looked for an "elisp style guide" in
emacs/docs/*, and in various READMEs, but didn't see anything obvious.

I find ^ and $ more readable (I had to look up \', and did not know
about \`). Although it does make sense to use the same style within one
regexp.

-- 
-- Stephe

Re: include Ada Reference Manual info files in ada-mode ELPA package?

[David Kastrup]

Stephen Leake <stephen_leake@stephe-leake.org> writes:

> Andreas Schwab <schwab@linux-m68k.org> writes:
>
>> Stephen Leake <stephen_leake@stephe-leake.org> writes:
>>
>>> --- a/admin/archive-contents.el
>>> +++ b/admin/archive-contents.el
>>> @@ -167,7 +167,7 @@ EXTRAS is an alist with additional metadata.
>>>  
>>>  PKG is the name of the package and DIR is the directory where it is."
>>>    (let* ((mainfile (expand-file-name (concat pkg ".el") dir))
>>> -         (files (directory-files dir nil "\\.el\\'")))
>>> +         (files (directory-files dir nil "^dir$\\|\\.el\\'")))
>>
>> Please use \` and \' instead of ^ and $.
>
> What is the rationale for that?

File names can contain newlines.

> Is it documented somewhere? I looked for an "elisp style guide" in
> emacs/docs/*, and in various READMEs, but didn't see anything obvious.

That's not a question of style.  The meaning is different.  Please check

(info "(Emacs) Regexps")

‘^’
     is a special character that matches the empty string, but only at
     the beginning of a line in the text being matched.  Otherwise it
     fails to match anything.  Thus, ‘^foo’ matches a ‘foo’ that occurs
     at the beginning of a line.

     For historical compatibility reasons, ‘^’ can be used with this
     meaning only at the beginning of the regular expression, or after
     ‘\(’ or ‘\|’.

‘$’
     is similar to ‘^’ but matches only at the end of a line.  Thus,
     ‘x+$’ matches a string of one ‘x’ or more at the end of a line.

     For historical compatibility reasons, ‘$’ can be used with this
     meaning only at the end of the regular expression, or before ‘\)’
     or ‘\|’.

and

(info "(Emacs) Regexp Backslash")

‘\`’
     matches the empty string, but only at the beginning of the string
     or buffer (or its accessible portion) being matched against.

‘\'’
     matches the empty string, but only at the end of the string or
     buffer (or its accessible portion) being matched against.

> I find ^ and $ more readable (I had to look up \', and did not know
> about \`). Although it does make sense to use the same style within one
> regexp.

It's not a question of style but of meaning.

-- 
David Kastrup

RE: include Ada Reference Manual info files in ada-mode ELPA package?

[Drew Adams]

> >> Please use \` and \' instead of ^ and $.
> > What is the rationale for that?
> File names can contain newlines.
> > Is it documented somewhere?
> 
> (info "(Emacs) Regexps")
> ‘^’
> ‘$’
> 
> and (info "(Emacs) Regexp Backslash")
> ‘\`’
> ‘\'’

It seems like this is a fairly common question/misunderstanding.
^ and $ were even used in the Emacs source code for a long time
in places where \` and \' are more appropriate.

It would be good to add cross-refs here (both directions), and to
explicitly point out what the difference is, and that while the
effect can sometimes be similar, \`...\' is often what you want
when matching strings.

Re: include Ada Reference Manual info files in ada-mode ELPA package?

[Stephen Leake]

David Kastrup <dak@gnu.org> writes:

> Stephen Leake <stephen_leake@stephe-leake.org> writes:
>
>> Andreas Schwab <schwab@linux-m68k.org> writes:
>>
>>> Stephen Leake <stephen_leake@stephe-leake.org> writes:
>>>
>>>> --- a/admin/archive-contents.el
>>>> +++ b/admin/archive-contents.el
>>>> @@ -167,7 +167,7 @@ EXTRAS is an alist with additional metadata.
>>>>  
>>>>  PKG is the name of the package and DIR is the directory where it is."
>>>>    (let* ((mainfile (expand-file-name (concat pkg ".el") dir))
>>>> -         (files (directory-files dir nil "\\.el\\'")))
>>>> +         (files (directory-files dir nil "^dir$\\|\\.el\\'")))
>>>
>>> Please use \` and \' instead of ^ and $.
>>
>> What is the rationale for that?
>
> File names can contain newlines.

Ah; I forgot/didn't realize that.

>
>> Is it documented somewhere? I looked for an "elisp style guide" in
>> emacs/docs/*, and in various READMEs, but didn't see anything obvious.
>
> That's not a question of style.  The meaning is different.  Please check
>
> (info "(Emacs) Regexps")
>
> ‘^’
>      is a special character that matches the empty string, but only at
>      the beginning of a line in the text being matched.  Otherwise it
>      fails to match anything.  Thus, ‘^foo’ matches a ‘foo’ that occurs
>      at the beginning of a line.

(info "(elisp) "Regexp Special") in 24.3.93.1 says:

^
     ...

     When matching a string instead of a buffer, `^' matches at the
     beginning of the string or after a newline character.

Which I read, and noticed was different from \`, but did not appreciate
the significance

-- 
-- Stephe

Re: include Ada Reference Manual info files in ada-mode ELPA package?

[Stephen Leake]

Drew Adams <drew.adams@oracle.com> writes:

>> >> Please use \` and \' instead of ^ and $.
>> > What is the rationale for that?
>> File names can contain newlines.
>> > Is it documented somewhere?
>> 
>> (info "(Emacs) Regexps")
>> ‘^’
>> ‘$’
>> 
>> and (info "(Emacs) Regexp Backslash")
>> ‘\`’
>> ‘\'’
>
> It seems like this is a fairly common question/misunderstanding.
> ^ and $ were even used in the Emacs source code for a long time
> in places where \` and \' are more appropriate.
>
> It would be good to add cross-refs here (both directions), and to
> explicitly point out what the difference is, and that while the
> effect can sometimes be similar, \`...\' is often what you want
> when matching strings.

The elisp manual is better for this than the Emacs manual; I suggest the
Emacs manual section on regexp be replaced by a cross-reference to the
elisp manual.

-- 
-- Stephe

Re: include Ada Reference Manual info files in ada-mode ELPA package?

[Stefan Monnier]

>> Perhaps making the ARM a separate ELPA package would be the right
>> choice. It would be an info-only package, so there would be no .el file
>> to hold the meta-data header. I guess I'd have to add one just for that.
>> Would that be ok?
> I tried this. It fails because `archive--metadata' in
> elpa/admin/archive-contents.el thinks it's a simple (one-file) package,
> because there is only one .el file.

Add

   ;; Package-Type: multi

in the .el file's header.


        Stefan

Re: include Ada Reference Manual info files in ada-mode ELPA package?

[Stephen Leake]

Stefan Monnier <monnier@IRO.UMontreal.CA> writes:

>>> Perhaps making the ARM a separate ELPA package would be the right
>>> choice. It would be an info-only package, so there would be no .el file
>>> to hold the meta-data header. I guess I'd have to add one just for that.
>>> Would that be ok?
>> I tried this. It fails because `archive--metadata' in
>> elpa/admin/archive-contents.el thinks it's a simple (one-file) package,
>> because there is only one .el file.
>
> Add
>
>    ;; Package-Type: multi
>
> in the .el file's header.

I missed that, although it is clear from the code I was reading. 

Still, I think it makes sense for the automatic determination be correct
in as many cases as reasonable; checking for 'dir' is cheap.

-- 
-- Stephe

Re: include Ada Reference Manual info files in ada-mode ELPA package?

[Stefan Monnier]

> Still, I think it makes sense for the automatic determination be correct
> in as many cases as reasonable; checking for 'dir' is cheap.

Then again, it's good when the "automatism" is sufficiently simple to
be predictable and easy to describe.


        Stefan