From bd74fefce24f1a9a7b6d3a7f1e17237a67e9d1d4 Mon Sep 17 00:00:00 2001 From: Štěpán Němec Date: Mon, 28 Aug 2023 12:42:46 +0200 Subject: Fix some typos/grammar/errors in docs and comments --- Documentation/RelNotes/v2.0.0.wip | 2 +- Documentation/dc-dlvr-spam-flow.txt | 2 +- Documentation/design_notes.txt | 10 +++++----- Documentation/design_www.txt | 12 ++++++------ Documentation/lei.pod | 2 +- Documentation/public-inbox-config.pod | 10 +++++----- Documentation/public-inbox-daemon.pod | 20 +++++++++++--------- Documentation/public-inbox-glossary.pod | 6 +++--- Documentation/public-inbox-learn.pod | 4 ++-- Documentation/public-inbox-purge.pod | 4 ++-- Documentation/public-inbox-tuning.pod | 12 ++++++------ Documentation/public-inbox-v2-format.pod | 6 +++--- Documentation/public-inbox-watch.pod | 4 ++-- Documentation/reproducibility.txt | 4 ++-- Documentation/standards.perl | 4 ++-- Documentation/technical/data_structures.txt | 28 ++++++++++++++-------------- Documentation/technical/ds.txt | 6 +++--- Documentation/technical/memory.txt | 2 +- Documentation/technical/whyperl.txt | 20 ++++++++++---------- 19 files changed, 80 insertions(+), 78 deletions(-) (limited to 'Documentation') diff --git a/Documentation/RelNotes/v2.0.0.wip b/Documentation/RelNotes/v2.0.0.wip index cccf11ae..40c87169 100644 --- a/Documentation/RelNotes/v2.0.0.wip +++ b/Documentation/RelNotes/v2.0.0.wip @@ -60,7 +60,7 @@ lei * fix `lei q -tt' on locally-indexed messages (still broken for remotes: https://public-inbox.org/meta/20230226170931.M947721@dcvr/ ) - * `lei import' now set labels+keywords consistently on all + * `lei import' now sets labels+keywords consistently on all already-imported messages solver (used by lei (rediff|blob), and PublicInbox::WWW) diff --git a/Documentation/dc-dlvr-spam-flow.txt b/Documentation/dc-dlvr-spam-flow.txt index d151d272..6210fc7d 100644 --- a/Documentation/dc-dlvr-spam-flow.txt +++ b/Documentation/dc-dlvr-spam-flow.txt @@ -39,7 +39,7 @@ delivery path as well as removing the message from the git tree. * incron - run commands based on filesystem events: http://incron.aiken.cz/ -* sendmail / MTA - we use and recommend use postfix, which includes a +* sendmail / MTA - we use and recommend postfix, which includes a sendmail-compatible wrapper: http://www.postfix.org/ * spamc / spamd - SpamAssassin: http://spamassassin.apache.org/ diff --git a/Documentation/design_notes.txt b/Documentation/design_notes.txt index 3df5af3e..95f02556 100644 --- a/Documentation/design_notes.txt +++ b/Documentation/design_notes.txt @@ -52,15 +52,15 @@ Why email? There is no need to ask the NSA for backups of your mail archives :) * git, one of the most widely-used version control systems, includes many - tools for for email, including: git-format-patch(1), git-send-email(1), + tools for email, including: git-format-patch(1), git-send-email(1), git-am(1), git-imap-send(1). Furthermore, the development of git itself is based on the git mailing list: https://public-inbox.org/git/ (or http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/git/ - for Tor users) + for Tor users). * Email is already the de-facto form of communication in many Free Software - communities.. + communities. * Fallback/transition to private email and other lists, in case the public-inbox host becomes unavailable, users may still directly email @@ -76,13 +76,13 @@ Why git? * As of 2016, git is widely used and known to nearly all Free Software developers. For non-developers it is packaged for all major GNU/Linux - and *BSD distributions. NNTP is not as widely-used nowadays, and + and *BSD distributions. NNTP is not as widely used nowadays, and most IMAP clients do not have good support for read-only mailboxes. Why perl 5? ----------- -* Perl 5 is widely available on modern *nix systems with good a history +* Perl 5 is widely available on modern *nix systems, with a good history of backwards and forward compatibility. * git and SpamAssassin both use it, so it should be one less thing for diff --git a/Documentation/design_www.txt b/Documentation/design_www.txt index b1f916dd..68488b1f 100644 --- a/Documentation/design_www.txt +++ b/Documentation/design_www.txt @@ -102,7 +102,7 @@ We also set to make window management easier. We favor <pre>-formatted text since public-inbox is intended as a place to share and discuss patches and code. Unfortunately, long paragraphs -tends to be less readable with fixed-width serif fonts which GUI +tend to be less readable with fixed-width serif fonts which GUI browsers default to. * No graphics, images, or icons at all. We tolerate, but do not @@ -122,12 +122,12 @@ browsers default to. avoided as they do not render well with some displays or user-chosen fonts. -* No JavaScript. JS is historically too buggy and insecure, and we will +* No JavaScript. JS is historically too buggy and insecure, and we will never expect our readers to do either of the following: - a) read and audit all our code for on every single page load - b) trust us and and run code without reading it + a) read and audit all our code on every single page load + b) trust us and run code without reading it -* We only use CSS for one reason: wrapping pre-formatted text +* We only use CSS for one reason: wrapping pre-formatted text. This is necessary because unfortunate GUI browsers tend to be prone to layout widening from unwrapped mailers. Do not expect CSS to be enabled, especially with scary things like: @@ -141,4 +141,4 @@ CSS classes (for user-supplied CSS) ----------------------------------- See examples in contrib/css/ and lib/PublicInbox/WwwText.pm -(or https://public-inbox.org/meta/_/text/color/ soon) +(or <https://public-inbox.org/meta/_/text/color/>) diff --git a/Documentation/lei.pod b/Documentation/lei.pod index f01f506a..2b10f490 100644 --- a/Documentation/lei.pod +++ b/Documentation/lei.pod @@ -126,7 +126,7 @@ Other subcommands include =head1 FILES -By default storage is located at C<$XDG_DATA_HOME/lei/store>. The +By default, storage is located at C<$XDG_DATA_HOME/lei/store>. The configuration for lei resides at C<$XDG_CONFIG_HOME/lei/config>. =head1 ERRORS diff --git a/Documentation/public-inbox-config.pod b/Documentation/public-inbox-config.pod index d175d2d7..d2389abc 100644 --- a/Documentation/public-inbox-config.pod +++ b/Documentation/public-inbox-config.pod @@ -191,7 +191,7 @@ Default: :all The local path name of a CSS file for the PSGI web interface. May contain the attributes "media", "title" and "href" which match the associated attributes of the HTML <style> tag. -"href" may be specified to point to the URL of an remote CSS file +"href" may be specified to point to the URL of a remote CSS file and the path may be "/dev/null" or any empty file. Multiple files may be specified and will be included in the order specified. @@ -291,10 +291,10 @@ Default: /var/www/htdocs/cgit/cgit.cgi or /usr/lib/cgit/cgit.cgi =item publicinbox.cgitdata A path to the data directory used by cgit for storing static files. -Typically guessed based the location of C<cgit.cgi> (from -C<publicinbox.cgitbin>, but may be overridden. +Typically guessed based on the location of C<cgit.cgi> (from +C<publicinbox.cgitbin>), but may be overridden. -Default: basename of C<publicinbox.cgitbin>, /var/www/htdocs/cgit/ +Default: dirname of C<publicinbox.cgitbin>, /var/www/htdocs/cgit/ or /usr/share/cgit/ =item publicinbox.cgit @@ -311,7 +311,7 @@ Try using C<cgit> as the first choice, this is the default. =item * fallback Fall back to using C<cgit> only if our native, inbox-aware -git code repository viewer doesn't recognized the URL. +git code repository viewer doesn't recognize the URL. =item * rewrite diff --git a/Documentation/public-inbox-daemon.pod b/Documentation/public-inbox-daemon.pod index 71216833..c5c88bdd 100644 --- a/Documentation/public-inbox-daemon.pod +++ b/Documentation/public-inbox-daemon.pod @@ -101,6 +101,8 @@ Default: 1 The default TLS certificate for HTTPS, IMAPS, NNTPS, POP3S and/or STARTTLS support if the C<cert> option is not given with C<--listen>. +=for comment FIXME this paragraph needs repair + Well-known TCP ports automatically get TLS or STARTTLS support If using systemd-compatible socket activation and a TCP listener on port well-known ports (563 is inherited, it is automatically @@ -112,15 +114,15 @@ STARTTLS support. The default TLS certificate key for the default C<--cert> or per-listener C<cert=> option. The private key may be -concatenated into the path used by the cert, in which case this +concatenated into the cert file itself, in which case this option is not needed. =item --multi-accept INTEGER -By default, each worker accepts one connection at-a-time to maximize +By default, each worker accepts one connection at a time to maximize fairness and minimize contention across multiple processes on a shared listen socket. Accepting multiple connections at once may be -useful in constrained deployments with few, heavily-loaded workers. +useful in constrained deployments with few, heavily loaded workers. Negative values enables a worker to accept all available clients at once, possibly starving others in the process. C<-1> behaves like C<multi_accept yes> in nginx; while C<0> (the default) is @@ -137,7 +139,7 @@ Default: 0 =head1 SIGNALS Most of our signal handling behavior is copied from L<nginx(8)> -and/or L<starman(1)>; so it is possible to reuse common scripts +and/or L<starman(1)>, so it is possible to reuse common scripts for managing them. =over 8 @@ -158,7 +160,7 @@ Reload config files associated with the process. =item SIGTTIN -Increase the number of running workers processes by one. +Increase the number of running worker processes by one. =item SIGTTOU @@ -166,7 +168,7 @@ Decrease the number of running worker processes by one. =item SIGWINCH -Stop all running worker processes. SIGHUP or SIGTTIN +Stop all running worker processes. SIGHUP or SIGTTIN may be used to restart workers. =item SIGQUIT @@ -194,7 +196,7 @@ activation. See L<systemd.socket(5)> and L<sd_listen_fds(3)>. =item PERL_INLINE_DIRECTORY -Pointing this to point to a writable directory enables the use +Pointing this to a writable directory enables the use of L<Inline> and L<Inline::C> extensions which may provide platform-specific performance improvements. Currently, this enables the use of L<vfork(2)> which speeds up subprocess @@ -211,8 +213,8 @@ created by a user. See L<Inline> and L<Inline::C> for more details. There are two ways to upgrade a running process. Users of process management systems with socket activation -(L<systemd(1)> or similar) may rely on multiple instances For -systemd, this means using two (or more) '@' instances for each +(L<systemd(1)> or similar) may rely on multiple daemon instances. +For systemd, this means using two (or more) '@' instances for each service (e.g. C<SERVICENAME@INSTANCE>) as documented in L<systemd.unit(5)>. diff --git a/Documentation/public-inbox-glossary.pod b/Documentation/public-inbox-glossary.pod index 3c9e2bd2..d88539c8 100644 --- a/Documentation/public-inbox-glossary.pod +++ b/Documentation/public-inbox-glossary.pod @@ -25,7 +25,7 @@ C<over.sqlite3> =item tid, THREADID -A sequentially-assigned positive integer. These integers are +A sequentially assigned positive integer. These integers are per-inbox or per-extindex. In the future, this may be prefixed with C<T> for JMAP (RFC 8621) and RFC 8474. This may not be strictly compliant with RFC 8621 since inboxes and extindices @@ -40,7 +40,7 @@ RFC-(822|2822|5322) email message. =item IMAP EMAILID, JMAP Email Id -To-be-decided. This will likely be the git blob ID prefixed with C<g> +To be decided. This will likely be the git blob ID prefixed with C<g> rather than the numeric UID to accommodate the same blob showing up in both an extindex and inbox (or multiple extindices). @@ -87,7 +87,7 @@ but it imports drafts. For L<lei(1)> users only. This will allow lei users to place the same email into one or more virtual folders for -ease-of-filtering. This is NOT tied to public-inbox names, as +ease of filtering. This is NOT tied to public-inbox names, as messages stored by lei may not be public. These are similar in spirit to arbitrary freeform "tags" diff --git a/Documentation/public-inbox-learn.pod b/Documentation/public-inbox-learn.pod index 3c92b1cc..f776df6b 100644 --- a/Documentation/public-inbox-learn.pod +++ b/Documentation/public-inbox-learn.pod @@ -54,7 +54,7 @@ This is similar to the C<spam> command above, but does not feed the message to L<spamc(1)> and only removes messages which match on any of the C<To:>, C<Cc:>, and C<List-ID:> headers. -The C<--all> option may be used match C<spam> semantics in removing +The C<--all> option may be used to match C<spam> semantics in removing the message from all configured inboxes. C<--all> is only available in public-inbox 1.6.0+. @@ -82,7 +82,7 @@ L<http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta/> =head1 COPYRIGHT -Copyright 2019-2021 all contributors L<mailto:meta@public-inbox.org> +Copyright all contributors L<mailto:meta@public-inbox.org> License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt> diff --git a/Documentation/public-inbox-purge.pod b/Documentation/public-inbox-purge.pod index 945286c6..1223b577 100644 --- a/Documentation/public-inbox-purge.pod +++ b/Documentation/public-inbox-purge.pod @@ -31,7 +31,7 @@ leads to discontiguous git history. =item --all Purge the message in all inboxes configured in ~/.public-inbox/config. -This is an alternative to specifying individual inboxes directories +This is an alternative to specifying individual inbox directories on the command-line. =back @@ -74,7 +74,7 @@ L<http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta/> =head1 COPYRIGHT -Copyright 2019-2021 all contributors L<mailto:meta@public-inbox.org> +Copyright all contributors L<mailto:meta@public-inbox.org> License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt> diff --git a/Documentation/public-inbox-tuning.pod b/Documentation/public-inbox-tuning.pod index 53668ecc..58a4d9bc 100644 --- a/Documentation/public-inbox-tuning.pod +++ b/Documentation/public-inbox-tuning.pod @@ -79,8 +79,8 @@ RAM. Attempts to parallelize random I/O on HDDs leads to pathological slowdowns as inboxes grow. While C<-V2> introduced Xapian shards as a parallelization -mechanism for SSDs; enabling C<publicInbox.indexSequentialShard> -repurposes sharding as mechanism to reduce the kernel page cache +mechanism for SSDs, enabling C<publicInbox.indexSequentialShard> +repurposes sharding as a mechanism to reduce the kernel page cache footprint when indexing on HDDs. Initializing a mirror with a high C<--jobs> count to create more @@ -108,7 +108,7 @@ indices on btrfs to achieve acceptable performance (even on SSD). Disabling copy-on-write also disables checksumming, thus C<raid1> (or higher) configurations may be corrupt after unsafe shutdowns. -Fortunately, these SQLite and Xapian indices are designed to +Fortunately, these SQLite and Xapian indices are designed to be recoverable from git if missing. Disabling CoW does not prevent all fragmentation. Large values @@ -125,7 +125,7 @@ C<btrfs filesystem defragment -fr $INBOX_DIR> may be necessary. Large filesystems benefit significantly from the C<space_cache=v2> mount option documented in L<btrfs(5)>. -Older, non-CoW filesystems are generally work well out-of-the-box +Older, non-CoW filesystems generally work well out of the box for our Xapian and SQLite indices. =head2 Performance on solid state drives @@ -152,7 +152,7 @@ C<LimitNOFILE=> in L<systemd.exec(5)>) may need to be raised to accommodate many concurrent clients. Transport Layer Security (IMAPS, NNTPS, or via STARTTLS) significantly -increases memory use of client sockets, sure to account for that in +increases memory use of client sockets, be sure to account for that in capacity planning. =head2 Other OS tuning knobs @@ -168,7 +168,7 @@ Other OSes may have similar tuning knobs (patches appreciated). L<public-inbox-extindex(1)> allows any number of public-inboxes to share the same Xapian indices. -git 2.33+ startup time is orders-of-magnitude faster and uses +git 2.33+ startup time is orders of magnitude faster and uses less memory when dealing with thousands of alternates required for thousands of inboxes with L<public-inbox-extindex(1)>. diff --git a/Documentation/public-inbox-v2-format.pod b/Documentation/public-inbox-v2-format.pod index e93d7fc7..de3b0bfd 100644 --- a/Documentation/public-inbox-v2-format.pod +++ b/Documentation/public-inbox-v2-format.pod @@ -30,7 +30,7 @@ databases for parallelism by "shards". - all.git # empty, alternates to $EPOCH.git - xap$SCHEMA_VERSION/$SHARD # per-shard Xapian DB - xap$SCHEMA_VERSION/over.sqlite3 # OVER-view DB for NNTP, threading - - msgmap.sqlite3 # same the v1 msgmap + - msgmap.sqlite3 # same as the v1 msgmap For blob lookups, the reader only needs to open the "all.git" repository with $GIT_DIR/objects/info/alternates which references @@ -89,7 +89,7 @@ After-the-fact invocations of L<public-inbox-index> will ignore messages written to 'd' after they are written to 'm'. Deltafication is not significantly improved over v1, but overall -storage for trees is made as as small as possible. Initial +storage for trees is made as small as possible. Initial statistics and benchmarks showing the benefits of this approach are documented at: @@ -97,7 +97,7 @@ L<https://public-inbox.org/meta/20180209205140.GA11047@dcvr/> =head2 XAPIAN SHARDS -Another second scalability problem in v1 was the inability to +Another scalability problem in v1 was the inability to utilize multiple CPU cores for Xapian indexing. This is addressed by using shards in Xapian to perform import indexing in parallel. diff --git a/Documentation/public-inbox-watch.pod b/Documentation/public-inbox-watch.pod index e8f97c80..febda0b1 100644 --- a/Documentation/public-inbox-watch.pod +++ b/Documentation/public-inbox-watch.pod @@ -41,7 +41,7 @@ importing them into public-inbox git repositories and indices. public-inbox-watch is useful in situations when a user wishes to mirror an existing mailing list, but has no access to run L<public-inbox-mda(1)> on a server. Unlike public-inbox-mda -which is invoked once per-message, public-inbox-watch is a +which is invoked once per message, public-inbox-watch is a persistent process, making it faster for after-the-fact imports of large Maildirs. @@ -62,7 +62,7 @@ public-inbox-watch takes no command-line options. =head1 CONFIGURATION These configuration knobs should be used in the -L<public-inbox-config(5)> file +L<public-inbox-config(5)> file. =over 8 diff --git a/Documentation/reproducibility.txt b/Documentation/reproducibility.txt index 4e56ada4..3336de73 100644 --- a/Documentation/reproducibility.txt +++ b/Documentation/reproducibility.txt @@ -12,7 +12,7 @@ reproducible. Keeping all communications as email ensures the full history of the entire project can be mirrored by anyone with the resources to do so. Compact, low-complexity data requires -less resources to mirror, so sticking with plain-text +less resources to mirror, so sticking with plain text ensures more parties can mirror and potentially fork the project with all its data. @@ -26,4 +26,4 @@ If these things make power hungry project leaders and admins uncomfortable, good. That was the point. It's how checks and balances ought to work. -Comments, corrections, etc welcome: meta@public-inbox.org +Comments, corrections, etc. welcome: meta@public-inbox.org diff --git a/Documentation/standards.perl b/Documentation/standards.perl index c36afb5d..743cdee1 100755 --- a/Documentation/standards.perl +++ b/Documentation/standards.perl @@ -11,11 +11,11 @@ Non-exhaustive list of standards public-inbox software attempts or intends to implement. This list is intended to be a quick reference for hackers and users. -Given the goals of interoperability and accessibility; strict +Given the goals of interoperability and accessibility, strict conformance to standards is not always possible, but rather best-effort taking into account real-world cases. In particular, "obsolete" standards remain relevant as long as clients and -data exists. +data using them exist. IETF RFCs --------- diff --git a/Documentation/technical/data_structures.txt b/Documentation/technical/data_structures.txt index 4dcf9ce6..5ed21882 100644 --- a/Documentation/technical/data_structures.txt +++ b/Documentation/technical/data_structures.txt @@ -32,19 +32,19 @@ Per-message classes Common abbreviation: $mime, $eml Used by: PublicInbox::WWW, PublicInbox::SearchIdx - An representation of an entire email, multipart or not. + A representation of an entire email, multipart or not. An option to use libgmime or libmailutils may be supported in the future for performance and memory use. This can be a memory hog with big messages and giant attachments, so our PublicInbox::WWW interface only keeps - one object of this class in memory at-a-time. + one object of this class in memory at a time. In other words, this is the "meat" of the message, whereas $smsg (below) is just the "skeleton". Our PublicInbox::V2Writable class may have two objects of this - type in memory at-a-time for deduplication. + type in memory at a time for deduplication. In public-inbox 1.4 and earlier, Email::MIME and its subclass, PublicInbox::MIME were used. Despite still slurping, @@ -61,10 +61,10 @@ Per-message classes This is loaded from either the overview DB (over.sqlite3) or the Xapian DB (docdata.glass), though the Xapian docdata - is won't hold NNTP-only fields (Cc:/To:) + won't hold NNTP-only fields (Cc:/To:). There may be hundreds or thousands of these objects in memory - at-a-time, so fields are pruned if unneeded. + at a time, so fields are pruned if unneeded. * PublicInbox::SearchThread::Msg - subclass of Smsg Common abbreviation: $cont or $node @@ -75,9 +75,9 @@ Per-message classes Nowadays, this is a re-blessed $smsg with additional fields. As with $smsg objects, there may be hundreds or thousands - of these objects in memory at-a-time. + of these objects in memory at a time. - We also do not use a linked-list for storing children as JWZ + We also do not use a linked list for storing children as JWZ describes, but instead a Perl hashref for {children} which becomes an arrayref upon sorting. @@ -88,7 +88,7 @@ Per-inbox classes * PublicInbox::Inbox - represents a single public-inbox Common abbreviation: $ibx - Used everywhere + Used everywhere. This represents a "publicinbox" section in the config file, see public-inbox-config(5) for details. @@ -152,7 +152,7 @@ ad-hoc structures shared across packages This holds the PSGI $env as well as any internal variables used by various modules of PublicInbox::WWW. - As with the PSGI $env, there is one per-active WWW + As with the PSGI $env, there is one per active WWW request+response cycle. It does not exist for idle HTTP clients. @@ -174,8 +174,8 @@ daemon classes Common abbreviation: $http Used by: PublicInbox::DS, public-inbox-httpd - Unlike PublicInbox::NNTP, this class no knowledge of any of - the email or git-specific parts of public-inbox, only PSGI. + Unlike PublicInbox::NNTP, this class has no knowledge of any of + the email- or git-specific parts of public-inbox, only PSGI. However, it supports APIs and behaviors (e.g. streaming large responses) which PublicInbox::WWW may take advantage of. @@ -188,7 +188,7 @@ daemon classes This class calls non-blocking accept(2) or accept4(2) on a listen socket to create new PublicInbox::HTTP and - PublicInbox::HTTP instances. + PublicInbox::NNTP instances. * PublicInbox::HTTPD Common abbreviation: $httpd @@ -197,9 +197,9 @@ daemon classes wrappers around client sockets accepted from PublicInbox::Listener. - Since the SERVER_NAME and SERVER_PORT PSGI variables needs to be + Since the SERVER_NAME and SERVER_PORT PSGI variables need to be exposed for HTTP/1.0 requests when Host: headers are missing, - this is per-Listener socket. + this is per Listener socket. * PublicInbox::HTTPD::Async Common abbreviation: $async diff --git a/Documentation/technical/ds.txt b/Documentation/technical/ds.txt index 4cfb62fe..afead2f1 100644 --- a/Documentation/technical/ds.txt +++ b/Documentation/technical/ds.txt @@ -19,7 +19,7 @@ Most notably: triggers a call. The lack of read/write callback distinction is driven by the - fact TLS libraries (e.g. OpenSSL via IO::Socket::SSL) may + fact that TLS libraries (e.g. OpenSSL via IO::Socket::SSL) may declare SSL_WANT_READ on SSL_write(), and SSL_WANT_READ on SSL_read(). So we end up having to let each user object decide whether it wants to make read or write calls depending on its @@ -35,7 +35,7 @@ Most notably: Reducing the user-supplied code down to a single callback allows subclasses to keep their logic self-contained. The combination of this change and one-shot wakeups (see below) for bidirectional - data flows make asynchronous code easier to reason about. + data flows makes asynchronous code easier to reason about. Other divergences: @@ -53,7 +53,7 @@ Other divergences: Augmented features: -* obj->write(CODEREF) passes the object itself to the CODEREF +* obj->write(CODEREF) passes the object itself to the CODEREF. Being able to enqueue subroutine calls is a powerful feature in Danga::Socket for keeping linear logic in an asynchronous environment. Unfortunately, each subroutine takes several kilobytes of memory. diff --git a/Documentation/technical/memory.txt b/Documentation/technical/memory.txt index a35b2c73..039694c3 100644 --- a/Documentation/technical/memory.txt +++ b/Documentation/technical/memory.txt @@ -8,7 +8,7 @@ memory-efficient. We strive to keep processes small to improve locality, allow the kernel to cache more files, and to be a good neighbor to other processes running on the machine. Taking advantage of -automatic reference counting (ARC) in Perl allows us +automatic reference counting (ARC) in Perl allows us to deterministically release memory back to the heap. We start with a simple data model with few circular diff --git a/Documentation/technical/whyperl.txt b/Documentation/technical/whyperl.txt index fbe2e1b1..db1d9793 100644 --- a/Documentation/technical/whyperl.txt +++ b/Documentation/technical/whyperl.txt @@ -21,7 +21,7 @@ Good Things Perl 5 is installed on many, if not most GNU/Linux and BSD-based servers and workstations. It is likely the most - widely-installed programming environment that offers a + widely installed programming environment that offers a significant amount of POSIX functionality. Users won't have to waste bandwidth or space with giant toolchains or architecture-specific binaries. @@ -47,8 +47,8 @@ Good Things * Predictable performance - While Perl is neither fast or memory-efficient, its - performance and memory use are predictable and does not + While Perl is neither fast nor memory-efficient, its + performance and memory use are predictable and do not require GC tuning by the user. public-inbox is developed for (and mostly on) old @@ -56,7 +56,7 @@ Good Things late 1990s, and any cheap VPS today has more than enough RAM and CPU for handling plain-text email. - Low hardware requirements increases the reach of our software + Low hardware requirements increase the reach of our software to more users, improving centralization resistance. * Compatibility @@ -86,7 +86,7 @@ Good Things There should be no need to rely on language-specific package managers such as cpan(1), those systems increase - the learning curve for users and systems administrators. + the learning curve for users and system administrators. * Compactness and terseness @@ -98,7 +98,7 @@ Good Things * Performance ceiling and escape hatch With optional Inline::C, we can be "as fast as C" in some - cases. Inline::C is widely-packaged by distros and it + cases. Inline::C is widely packaged by distros and it gives us an escape hatch for dealing with missing bindings or performance problems should they arise. Inline::C use (as opposed to XS) also preserves the software freedom and @@ -135,7 +135,7 @@ Bad Things (m//, substr(), index(), etc.) still require memory copies into userspace, negating a benefit of zero-copy. -* The XS/C API make it difficult to improve internals while +* The XS/C API makes it difficult to improve internals while preserving compatibility. * Lack of optional type checking. This may be a blessing in @@ -161,14 +161,14 @@ Red herrings to ignore when evaluating other runtimes ----------------------------------------------------- These don't discount a language or runtime from being -being used, they're just not interesting. +used, they're just not interesting. * Lightweight threading While lightweight threading implementations are - convenient, they tend to be significantly heavier than a + convenient, they tend to be significantly heavier than pure event-loop systems (or multi-threaded event-loop - systems) + systems). Lightweight threading implementations have stack overhead and growth typically measured in kilobytes. The userspace -- cgit v1.2.3-24-ge0c7