branch: externals-release/plz
commit 3472d24120a1acaecfb2f436f75cdcf2ae15406f
Author: Adam Porter <a...@alphapapa.net>
Commit: Adam Porter <a...@alphapapa.net>
Fix: Info manual generation
GNU ELPA's build process complained that:
Manual name "README.html" conflicts with "activities/README.html"
So this implements the same pattern used in activities.el's readme,
which works on ELPA.
---
README.org | 18 +-
plz.info | 602 -------------------------------------------------------------
2 files changed, 9 insertions(+), 611 deletions(-)
diff --git a/README.org b/README.org
index 2d9bbbb620..d12bcb3df7 100644
--- a/README.org
+++ b/README.org
@@ -2,6 +2,12 @@
#+PROPERTY: LOGGING nil
+# NOTE: It would be preferable to put these at the bottom of the file under
the export options heading, but it seems that "TEXINFO_DIR_CATEGORY" only works
at the top of the file.
+#+EXPORT_FILE_NAME: plz.texi
+#+TEXINFO_DIR_CATEGORY: Emacs
+#+TEXINFO_DIR_TITLE: Plz: (plz)
+#+TEXINFO_DIR_DESC: HTTP library using Curl as a backend
+
# Note: This readme works with the org-make-toc
<https://github.com/alphapapa/org-make-toc> package, which automatically
updates the table of contents.
[[http://elpa.gnu.org/packages/plz.html][file:http://elpa.gnu.org/packages/plz.svg]]
@@ -181,7 +187,8 @@ You may also clear a queue with ~plz-clear~, which cancels
any active or queued
** 0.7.3-pre
-Nothing new yet.
+*Fixes*
++ Info manual generation on GNU ELPA. (Also, the Info manual is no longer
committed to Git.)
** 0.7.2
@@ -316,13 +323,7 @@ GPLv3
** Info export options
-#+TEXINFO_DIR_CATEGORY: Emacs
-#+TEXINFO_DIR_TITLE: Plz: (plz)
-#+TEXINFO_DIR_DESC: HTTP library using Curl as a backend
-
-# NOTE: We could use these, but that causes a pointless error,
"org-compile-file: File "..README.info" wasn't produced...", so we just rename
the files in the after-save-hook instead.
-# #+TEXINFO_FILENAME: plz.info
-# #+EXPORT_FILE_NAME: plz.texi
+# NOTE: These are moved to the top of the file.
** File-local variables
@@ -330,7 +331,6 @@ GPLv3
# Local Variables:
# eval: (require 'org-make-toc)
-# after-save-hook: (lambda nil (when (and (require 'ox-texinfo nil t)
(org-texinfo-export-to-info)) (delete-file "README.texi") (rename-file
"README.info" "plz.info" t)))
# before-save-hook: org-make-toc
# org-export-with-properties: ()
# org-export-with-title: t
diff --git a/plz.info b/plz.info
deleted file mode 100644
index 267ce6ed93..0000000000
--- a/plz.info
+++ /dev/null
@@ -1,602 +0,0 @@
-This is README.info, produced by makeinfo version 6.7 from README.texi.
-
-INFO-DIR-SECTION Emacs
-START-INFO-DIR-ENTRY
-* Plz: (plz). HTTP library using Curl as a backend.
-END-INFO-DIR-ENTRY
-
-
-File: README.info, Node: Top, Next: Installation, Up: (dir)
-
-plz.el
-******
-
-file:http://elpa.gnu.org/packages/plz.svg
-(http://elpa.gnu.org/packages/plz.html)
-
- ‘plz’ is an HTTP library for Emacs. It uses ‘curl’ as a backend,
-which avoids some of the issues with using Emacs’s built-in ‘url’
-library. It supports both synchronous and asynchronous requests. Its
-API is intended to be simple, natural, and expressive. Its code is
-intended to be simple and well-organized. Every feature is tested
-against httpbin (https://httpbin.org/).
-
-* Menu:
-
-* Installation::
-* Usage::
-* Changelog::
-* Credits::
-* Development::
-* License::
-
-— The Detailed Node Listing —
-
-Installation
-
-* GNU ELPA::
-* Manual::
-
-Usage
-
-* Examples::
-* Functions::
-* Queueing::
-* Tips::
-
-Changelog
-
-* 0.7.2: 072.
-* 0.7.1: 071.
-* 0.7: 07.
-* 0.6: 06.
-* 0.5.4: 054.
-* 0.5.3: 053.
-* 0.5.2: 052.
-* 0.5.1: 051.
-* 0.5: 05.
-* 0.4: 04.
-* 0.3: 03.
-* 0.2.1: 021.
-* 0.2: 02.
-* 0.1: 01.
-
-Development
-
-* Copyright assignment::
-
-
-
-File: README.info, Node: Installation, Next: Usage, Prev: Top, Up: Top
-
-1 Installation
-**************
-
-* Menu:
-
-* GNU ELPA::
-* Manual::
-
-
-File: README.info, Node: GNU ELPA, Next: Manual, Up: Installation
-
-1.1 GNU ELPA
-============
-
-‘plz’ is available in GNU ELPA (http://elpa.gnu.org/packages/plz.html).
-It may be installed in Emacs using the ‘package-install’ command.
-
-
-File: README.info, Node: Manual, Prev: GNU ELPA, Up: Installation
-
-1.2 Manual
-==========
-
-‘plz’ has no dependencies other than Emacs and ‘curl’. It’s known to
-work on Emacs 26.3 or later. To install it manually, simply place
-‘plz.el’ in your ‘load-path’ and ‘(require 'plz)’.
-
-
-File: README.info, Node: Usage, Next: Changelog, Prev: Installation, Up:
Top
-
-2 Usage
-*******
-
-The main public function is ‘plz’, which sends an HTTP request and
-returns either the result of the specified type (for a synchronous
-request), or the ‘curl’ process object (for asynchronous requests). For
-asynchronous requests, callback, error-handling, and finalizer functions
-may be specified, as well as various other options.
-
-* Menu:
-
-* Examples::
-* Functions::
-* Queueing::
-* Tips::
-
-
-File: README.info, Node: Examples, Next: Functions, Up: Usage
-
-2.1 Examples
-============
-
-Synchronously ‘GET’ a URL and return the response body as a decoded
-string (here, raw JSON):
-
- (plz 'get "https://httpbin.org/user-agent";)
-
- "{\n \"user-agent\": \"curl/7.35.0\"\n}\n"
-
- Synchronously ‘GET’ a URL that returns a JSON object, and parse and
-return it as an alist:
-
- (plz 'get "https://httpbin.org/get"; :as #'json-read)
-
- ((args)
- (headers
- (Accept . "*/*")
- (Accept-Encoding . "deflate, gzip")
- (Host . "httpbin.org")
- (User-Agent . "curl/7.35.0"))
- (url . "https://httpbin.org/get";))
-
- Asynchronously ‘POST’ a JSON object in the request body, then parse a
-JSON object from the response body, and call a function with the result:
-
- (plz 'post "https://httpbin.org/post";
- :headers '(("Content-Type" . "application/json"))
- :body (json-encode '(("key" . "value")))
- :as #'json-read
- :then (lambda (alist)
- (message "Result: %s" (alist-get 'data alist))))
-
- Result: {"key":"value"}
-
- Synchronously download a JPEG file, then create an Emacs image object
-from the data:
-
- (let ((jpeg-data (plz 'get "https://httpbin.org/image/jpeg"; :as 'binary)))
- (create-image jpeg-data nil 'data))
-
- (image :type jpeg :data ""ÿØÿà^@^PJFIF...")
-
-
-File: README.info, Node: Functions, Next: Queueing, Prev: Examples, Up:
Usage
-
-2.2 Functions
-=============
-
-‘plz’
- _(method url &key headers body else finally noquery (as ’string)
- (then ’sync) (body-type ’text) (decode t decode-s) (connect-timeout
- plz-connect-timeout) (timeout plz-timeout))_
-
- Request ‘METHOD’ from ‘URL’ with curl. Return the curl process
- object or, for a synchronous request, the selected result.
-
- ‘HEADERS’ may be an alist of extra headers to send with the
- request.
-
- ‘BODY’ may be a string, a buffer, or a list like ‘(file FILENAME)’
- to upload a file from disk.
-
- ‘BODY-TYPE’ may be ‘text’ to send ‘BODY’ as text, or ‘binary’ to
- send it as binary.
-
- ‘AS’ selects the kind of result to pass to the callback function
- ‘THEN’, or the kind of result to return for synchronous requests.
- It may be:
-
- • ‘buffer’ to pass the response buffer, which will be narrowed
- to the response body and decoded according to ‘DECODE’.
- • ‘binary’ to pass the response body as an un-decoded string.
- • ‘string’ to pass the response body as a decoded string.
- • ‘response’ to pass a ‘plz-response’ structure.
- • ‘file’ to pass a temporary filename to which the response body
- has been saved without decoding.
- • ‘(file ~FILENAME)’ to pass ‘FILENAME’ after having saved the
- response body to it without decoding. ‘FILENAME’ must be a
- non-existent file; if it exists, it will not be overwritten,
- and an error will be signaled.
- • A function, which is called in the response buffer with it
- narrowed to the response body (suitable for, e.g.
- ‘json-read’).
-
- If ‘DECODE’ is non-nil, the response body is decoded automatically.
- For binary content, it should be nil. When ‘AS’ is ‘binary’,
- ‘DECODE’ is automatically set to nil.
-
- ‘THEN’ is a callback function, whose sole argument is selected
- above with ‘AS’; if the request fails and no ‘ELSE’ function is
- given (see below), the argument will be a ‘plz-error’ structure
- describing the error. Or ‘THEN’ may be ‘sync’ to make a
- synchronous request, in which case the result is returned directly
- from this function.
-
- ‘ELSE’ is an optional callback function called when the request
- fails (i.e. if curl fails, or if the ‘HTTP’ response has a non-2xx
- status code). It is called with one argument, a ‘plz-error’
- structure. If ‘ELSE’ is nil, a ‘plz-curl-error’ or
- ‘plz-http-error’ is signaled when the request fails, with a
- ‘plz-error’ structure as the error data. For synchronous requests,
- this argument is ignored.
-
- ‘NOTE’: In v0.8 of ‘plz’, only one error will be signaled:
- ‘plz-error’. The existing errors, ‘plz-curl-error’ and
- ‘plz-http-error’, inherit from ‘plz-error’ to allow applications to
- update their code while using v0.7 (i.e. any ‘condition-case’
- forms should now handle only ‘plz-error’, not the other two).
-
- ‘FINALLY’ is an optional function called without argument after
- ‘THEN’ or ‘ELSE’, as appropriate. For synchronous requests, this
- argument is ignored.
-
- ‘CONNECT-TIMEOUT’ and ‘TIMEOUT’ are a number of seconds that limit
- how long it takes to connect to a host and to receive a response
- from a host, respectively.
-
- ‘NOQUERY’ is passed to ‘make-process’, which see.
-
-
-File: README.info, Node: Queueing, Next: Tips, Prev: Functions, Up: Usage
-
-2.3 Queueing
-============
-
-‘plz’ provides a simple system for queueing HTTP requests. First, make
-a ‘plz-queue’ struct by calling ‘make-plz-queue’. Then call ‘plz-queue’
-with the struct as the first argument, and the rest of the arguments
-being the same as those passed to ‘plz’. Then call ‘plz-run’ to run the
-queued requests.
-
- All of the queue-related functions return the queue as their value,
-making them easy to use. For example:
-
- (defvar my-queue (make-plz-queue :limit 2))
-
- (plz-run
- (plz-queue my-queue
- 'get "https://httpbin.org/get?foo=0";
- :then (lambda (body) (message "%s" body))))
-
- Or:
-
- (let ((queue (make-plz-queue :limit 2
- :finally (lambda ()
- (message "Queue empty."))))
- (urls '("https://httpbin.org/get?foo=0";
- "https://httpbin.org/get?foo=1";)))
- (plz-run
- (dolist (url urls queue)
- (plz-queue queue 'get url
- :then (lambda (body) (message "%s" body))))))
-
- You may also clear a queue with ‘plz-clear’, which cancels any active
-or queued requests and calls their ‘:else’ functions. And ‘plz-length’
-returns the number of a queue’s active and queued requests.
-
-
-File: README.info, Node: Tips, Prev: Queueing, Up: Usage
-
-2.4 Tips
-========
-
- • You can customize settings in the ‘plz’ group, but this can only be
- used to adjust a few defaults. It’s not intended that changing or
- binding global variables be necessary for normal operation.
-
-
-File: README.info, Node: Changelog, Next: Credits, Prev: Usage, Up: Top
-
-3 Changelog
-***********
-
-* Menu:
-
-* 0.7.2: 072.
-* 0.7.1: 071.
-* 0.7: 07.
-* 0.6: 06.
-* 0.5.4: 054.
-* 0.5.3: 053.
-* 0.5.2: 052.
-* 0.5.1: 051.
-* 0.5: 05.
-* 0.4: 04.
-* 0.3: 03.
-* 0.2.1: 021.
-* 0.2: 02.
-* 0.1: 01.
-
-
-File: README.info, Node: 072, Next: 071, Up: Changelog
-
-3.1 0.7.2
-=========
-
-*Fixes*
- • Don’t delete preexisting files when downloading to a file. (#41
- (https://github.com/alphapapa/plz.el/pull/41). Thanks to Joseph
- Turner (https://github.com/josephmturner).)
-
-
-File: README.info, Node: 071, Next: 07, Prev: 072, Up: Changelog
-
-3.2 0.7.1
-=========
-
-*Fixes*
- • Handle HTTP 303 redirects. (Thanks to Daniel Hubmann
- (https://github.com/hubisan) for reporting.)
-
-
-File: README.info, Node: 07, Next: 06, Prev: 071, Up: Changelog
-
-3.3 0.7
-=======
-
-*Changes*
- • A new error signal, ‘plz-error’, is defined. The existing signals,
- ‘plz-curl-error’ and ‘plz-http-error’, inherit from it, so handling
- ‘plz-error’ catches both.
-
- *NOTE:* The existing signals, ‘plz-curl-error’ and
- ‘plz-http-error’, are hereby deprecated, and they will be removed
- in v0.8. Applications should be updated while using v0.7 to only
- expect ‘plz-error’.
-
- *Fixes*
- • Significant improvement in reliability by implementing failsafes
- and workarounds for Emacs’s process-handling code. (See #3
- (https://github.com/alphapapa/plz.el/issues/3).)
- • STDERR output from curl processes is not included in response
- bodies (which sometimes happened, depending on Emacs’s internal
- race conditions). (Fixes #23
- (https://github.com/alphapapa/plz.el/issues/23).)
- • Use ‘with-local-quit’ for synchronous requests (preventing Emacs
- from complaining sometimes). (Fixes #26
- (https://github.com/alphapapa/plz.el/issues/26).)
- • Various fixes for ‘:as 'buffer’ result type: decode body when
- appropriate; unset multibyte for binary; narrow to body; don’t kill
- buffer prematurely.
- • When clearing a queue, don’t try to kill finished processes.
-
- *Internal*
- • Response processing now happens outside the process sentinel, so
- any errors (e.g. in user callbacks) are not signaled from inside
- the sentinel. (This avoids the 2-second pause Emacs imposes in
- such cases.)
- • Tests run against a local instance of httpbin
- (https://github.com/postmanlabs/httpbin) (since the ‘httpbin.org’
- server is often overloaded).
- • No buffer-local variables are defined anymore; process properties
- are used instead.
-
-
-File: README.info, Node: 06, Next: 054, Prev: 07, Up: Changelog
-
-3.4 0.6
-=======
-
-*Additions*
- • Function ‘plz’’s ‘:body’ argument now accepts a list like ‘(file
- FILENAME)’ to upload a file from disk (by passing the filename to
- curl, rather than reading its content into Emacs and sending it to
- curl through the pipe).
-
- *Fixes*
- • Function ‘plz’’s docstring now mentions that the ‘:body’ argument
- may also be a buffer (an intentional feature that was accidentally
- undocumented).
- • Handle HTTP 3xx redirects when using ‘:as 'response’.
-
-
-File: README.info, Node: 054, Next: 053, Prev: 06, Up: Changelog
-
-3.5 0.5.4
-=========
-
-*Fixes*
- • Only run queue’s ‘finally’ function after queue is empty. (New
- features should not be designed and released on a Friday.)
-
-
-File: README.info, Node: 053, Next: 052, Prev: 054, Up: Changelog
-
-3.6 0.5.3
-=========
-
-*Fixes*
- • Move new slot in ‘plz-queue’ struct to end to prevent invalid
- byte-compiler expansions for already-compiled applications (which
- would require them to be recompiled after upgrading ‘plz’).
-
-
-File: README.info, Node: 052, Next: 051, Prev: 053, Up: Changelog
-
-3.7 0.5.2
-=========
-
-*Fixes*
- • When clearing a queue, only call ‘plz-queue’’s ‘finally’ function
- when specified.
-
-
-File: README.info, Node: 051, Next: 05, Prev: 052, Up: Changelog
-
-3.8 0.5.1
-=========
-
-*Fixes*
- • Only call ‘plz-queue’’s ‘finally’ function when specified. (Thanks
- to Dan Oriani (https://github.com/redchops) for reporting.)
-
-
-File: README.info, Node: 05, Next: 04, Prev: 051, Up: Changelog
-
-3.9 0.5
-=======
-
-*Additions*
- • Struct ‘plz-queue’’s ‘finally’ slot, a function called when the
- queue is finished.
-
-
-File: README.info, Node: 04, Next: 03, Prev: 05, Up: Changelog
-
-3.10 0.4
-========
-
-*Additions*
- • Support for HTTP ‘HEAD’ requests. (Thanks to Inc. for
- sponsoring.)
-
- *Changes*
- • Allow sending ‘POST’ and ‘PUT’ requests without bodies. (#16
- (https://github.com/alphapapa/plz.el/issues/16). Thanks to Joseph
- Turner (https://github.com/josephmturner) for reporting. Thanks to
- Inc. for sponsoring.)
-
- *Fixes*
- • All 2xx HTTP status codes are considered successful. (#17
- (https://github.com/alphapapa/plz.el/issues/17). Thanks to Joseph
- Turner (https://github.com/josephmturner) for reporting. Thanks to
- Inc. for sponsoring.)
- • Errors are signaled with error data correctly.
-
- *Internal*
- • Test suite explicitly tests with both HTTP/1.1 and HTTP/2.
- • Test suite also tests with Emacs versions 27.2, 28.1, and 28.2.
-
-
-File: README.info, Node: 03, Next: 021, Prev: 04, Up: Changelog
-
-3.11 0.3
-========
-
-*Additions*
- • Handle HTTP proxy headers from Curl. (#2
- (https://github.com/alphapapa/plz.el/issues/2). Thanks to Alan
- Third (https://github.com/alanthird) and Sawyer Zheng
- (https://github.com/sawyerzheng) for reporting.)
-
- *Fixes*
- • Replaced words not in Ispell’s default dictionaries (so ‘checkdoc’
- linting succeeds).
-
-
-File: README.info, Node: 021, Next: 02, Prev: 03, Up: Changelog
-
-3.12 0.2.1
-==========
-
-*Fixes*
- • Handle when Curl process is interrupted.
-
-
-File: README.info, Node: 02, Next: 01, Prev: 021, Up: Changelog
-
-3.13 0.2
-========
-
-*Added*
- • Simple request queueing.
-
-
-File: README.info, Node: 01, Prev: 02, Up: Changelog
-
-3.14 0.1
-========
-
-Initial release.
-
-
-File: README.info, Node: Credits, Next: Development, Prev: Changelog, Up:
Top
-
-4 Credits
-*********
-
- • Thanks to Chris Wellons (https://github.com/skeeto), author of the
- Elfeed (https://github.com/skeeto/elfeed) feed reader and the
- popular blog null program (https://nullprogram.com/), for his
- invaluable advice, review, and encouragement.
-
-
-File: README.info, Node: Development, Next: License, Prev: Credits, Up: Top
-
-5 Development
-*************
-
-Bug reports, feature requests, suggestions — _oh my_!
-
- Note that ‘plz’ is a young library, and its only client so far is
-Ement.el (https://github.com/alphapapa/ement.el). There are a variety
-of HTTP and ‘curl’ features it does not yet support, since they have not
-been needed by the author. Patches are welcome, as long as they include
-passing tests.
-
-* Menu:
-
-* Copyright assignment::
-
-
-File: README.info, Node: Copyright assignment, Up: Development
-
-5.1 Copyright assignment
-========================
-
-This package is part of GNU Emacs (https://www.gnu.org/software/emacs/),
-being distributed in GNU ELPA (https://elpa.gnu.org/). Contributions to
-this project must follow GNU guidelines, which means that, as with other
-parts of Emacs, patches of more than a few lines must be accompanied by
-having assigned copyright for the contribution to the FSF. Contributors
-who wish to do so may contact emacs-de...@gnu.org <emacs-de...@gnu.org>
-to request the assignment form.
-
-
-File: README.info, Node: License, Prev: Development, Up: Top
-
-6 License
-*********
-
-GPLv3
-
-
-
-Tag Table:
-Node: Top199
-Node: Installation1208
-Node: GNU ELPA1351
-Node: Manual1597
-Node: Usage1903
-Node: Examples2404
-Node: Functions3771
-Node: Queueing7468
-Node: Tips8851
-Node: Changelog9152
-Node: 0729441
-Node: 0719725
-Node: 079938
-Node: 0611826
-Node: 05412437
-Node: 05312680
-Node: 05212996
-Node: 05113203
-Node: 0513455
-Node: 0413661
-Node: 0314569
-Node: 02115019
-Node: 0215170
-Node: 0115301
-Node: Credits15397
-Node: Development15763
-Node: Copyright assignment16277
-Node: License16865
-
-End Tag Table
-
-
-Local Variables:
-coding: utf-8
-End:
![http://elpa.gnu.org/packages/plz.html][file:http://elpa.gnu.org/packages/plz.svg](http://elpa.gnu.org/packages/plz.html][file:http://elpa.gnu.org/packages/plz.svg){kind=link}
