Style and grammar update to Markdown files

This commit majorly updates all Markdown documents by attempting to maintain a consistent (80 columns per line) formatting and addresses some display bugs in other Markdown renderers due to improper use of Markdown - GitHub is a little broken. But it also addresses grammar and even makes semantical changes to some paragraphs.

Notably, in README.md, section "System authentication helper binaries" had relatively severe changes.

To future contributors: if trying to maintain any kind of wrapping standard, I suggest using special extensions, like Rewrap for VSCode.

.github/CODE_OF_CONDUCT.md

@@ -1,33 +1,52 @@
 # Code of Merit
 
-**1.** The project creators, lead developers, core team, constitute the managing members of the project and have final say in every decision of the project, technical or otherwise, including overruling previous decisions. There are no limitations to this decisional power.
+**1.** The project creators, lead developers, core team, constitute the managing
+members of the project and have final say in every decision of the project,
+technical or otherwise, including overruling previous decisions. There are no
+limitations to this decisional power.
 
-**2.** Contributions are an expected result of your membership on the project. Don’t expect others to do your work or help you with your work forever.
+**2.** Contributions are an expected result of your membership on the project.
+Don’t expect others to do your work or help you with your work forever.
 
-**3.** All members have the same opportunities to seek any challenge they want within the project.
+**3.** All members have the same opportunities to seek any challenge they want
+within the project.
 
-**4.** Authority or position in the project will be proportional to the accrued contribution. Seniority must be earned.
+**4.** Authority or position in the project will be proportional to the accrued
+contribution. Seniority must be earned.
 
-**5.** Software is evolutive: the better implementations must supersede lesser implementations. Technical advantage is the primary evaluation metric.
+**5.** Software is evolutive: the better implementations must supersede lesser
+implementations. Technical advantage is the primary evaluation metric.
 
-**6.** This is a space for technical prowess; topics outside of the project will not be tolerated.
+**6.** This is a space for technical prowess; topics outside of the project will
+not be tolerated.
 
-**7.** Non technical conflicts will be discussed in a separate space. Disruption of the project will not be allowed.
+**7.** Non technical conflicts will be discussed in a separate space. Disruption
+of the project will not be allowed.
 
-**8.** Individual characteristics, including but not limited to, body, sex, sexual preference, race, language, religion, nationality, or political preferences are irrelevant in the scope of the project and will not be taken into account concerning your value or that of your contribution to the project.
+**8.** Individual characteristics, including but not limited to, body, sex,
+sexual preference, race, language, religion, nationality, or political
+preferences are irrelevant in the scope of the project and will not be taken
+into account concerning your value or that of your contribution to the project.
 
 **9.** Discuss or debate the idea, not the person.
 
-**10.** There is no room for ambiguity: Ambiguity will be met with questioning; further ambiguity will be met with silence. It is the responsibility of the originator to provide requested context.
+**10.** There is no room for ambiguity: Ambiguity will be met with questioning;
+further ambiguity will be met with silence. It is the responsibility of the
+originator to provide requested context.
 
-**11.** If something is illegal outside the scope of the project, it is illegal in the scope of the project. This Code of Merit does not take precedence over governing law.
+**11.** If something is illegal outside the scope of the project, it is illegal
+in the scope of the project. This Code of Merit does not take precedence over
+governing law.
 
-**12.** This Code of Merit governs the technical procedures of the project not the activities outside of it.
+**12.** This Code of Merit governs the technical procedures of the project not
+the activities outside of it.
 
 **13.** Participation on the project equates to agreement of this Code of Merit.
 
-**14.** No objectives beyond the stated objectives of this project are relevant to the project. Any intent to deviate the project from its original purpose of existence will constitute grounds for remedial action which may include expulsion from the project.
+**14.** No objectives beyond the stated objectives of this project are relevant
-
+to the project. Any intent to deviate the project from its original purpose of
-This document is the Code of Merit (<strike>`http://code-of-merit.org`</strike>), version 1.0.
+existence will constitute grounds for remedial action which may include
-
+expulsion from the project.
 
+This document is the Code of Merit
+(<strike>`http://code-of-merit.org`</strike>), version 1.0.

.github/CONTRIBUTING.md

@@ -6,7 +6,8 @@ better.
 ## Reporting bugs
 
 **Issue tracker is meant to be used only if you have a problem or a feature
-request. If you just have some questions about maddy - prefer to use the [IRC channel](https://webchat.freenode.net/?channels=%23%23maddy).**
+request. If you just have some questions about maddy - prefer to use the
+[IRC channel](https://webchat.freenode.net/?channels=%23%23maddy).**
 
 - Provide log files, preferably with 'debug' directive set.
 - Provide the exact steps to reproduce the issue.

.github/ISSUE_TEMPLATE/bug-report.md

@@ -19,7 +19,8 @@ Use a service like hastebin.com or attach a file if it is big
 
 # Configuration file
 
-Located in /etc/maddy/maddy.conf by default, don't forget to remove DB passwords and other security-related stuff.
+Located in /etc/maddy/maddy.conf by default, don't forget to remove DB passwords
+and other security-related stuff.
 
 # Environment information
 

.github/ISSUE_TEMPLATE/feature-request.md

@@ -16,6 +16,7 @@ Note alternatives you considered and why they are not useful.
 # Your idea for a solution
 
 How your solution would work in general?
-Note that some overly complicated solutions may be rejected because maddy is meant to be simple.
+Note that some overly complicated solutions may be rejected because maddy is
+meant to be simple.
 
 - [ ] I'm willing to help with the implementation

HACKING.md

@@ -1,31 +1,31 @@
 ## Design goals
 
-- **Make it easy to deploy**
+- **Make it easy to deploy.**
-  Minimal configuration changes should be required to get typical mail server
+  Minimal configuration changes should be required to get a typical mail server
-  running. Though, it is important to avoid making guesses for "zero
+  running. Though, it is important to avoid making guesses for a
-  configuration". Wrong guess is worse than no guess.
+  "zero-configuration". A wrong guess is worse than no guess.
 
-- **Provide 80% of needed components**
+- **Provide 80% of needed components.**
   E-mail has evolved into a huge mess. With a single package to do one thing, it
-  quickly turns into maintenance nightmare. Put all stuff mail server typically
+  quickly turns into a maintenance nightmare. Put all stuff mail server
-  needs into a single package. Though, leave controversial or highly opinionated
+  typically needs into a single package. Though, leave controversial or highly
-  stuff out, don't force people to do things our way (see next point).
+  opinionated stuff out, don't force people to do things our way
+  (see next point).
 
-- **Interoperate with existing software**
+- **Interoperate with existing software.**
   Implement (de-facto) standard protocols not only for clients but also for
   various server-side helper software (content filters, etc).
 
-- **Be secure but interoperable**
+- **Be secure but interoperable.**
   Verify DKIM signatures by default, use DMRAC policies by default, etc. This
   makes default setup as secure as possible while maintaining reasonable
-  interoperability. Users can configure maddy to be more strict at cost of
+  interoperability. Though, users can configure maddy to be stricter.
-  interoperability.
 
-- **Acheive flexibility through composability**
+- **Achieve flexibility through composability.**
-  Allow to connect components in arbitrary ways instead of restricting users to
+  Allow connecting components in arbitrary ways instead of restricting users to
   predefined templates.
 
-- **Use Go concurrency features to full extent**
+- **Use Go concurrency features to a full extent.**
   Do as much I/O as possible in parallel to minimize latencies. It is silly to
   not do so when it is possible.
 
@@ -38,7 +38,7 @@ user documentation to understand how things work from the user perspective as
 well.
 
 - User documentation: [maddy.conf(5)](maddy.conf.5.scd)
-- Design rationale: [Comments on design (Wiki)](https://github.com/foxcpp/maddy/wiki/Dev:-Comments-on-design)
+- Design rationale: [Comments on design (Wiki)][1]
 
 There are components called "modules". They are represented by objects
 implementing the module.Module interface. Each module gets its unique name.
@@ -76,15 +76,15 @@ that upstream. Unique names requirement helps a lot here.
 "Semantical names" idea explained above is not applied when modules instances
 are defined "inline" (in place they are used in). These instances have no
 instance names and are not added to the global map so they can not be accessed
-by modules other than one that used ConfigFromNode on corresponding config
+by modules other than one that used ConfigFromNode on the corresponding config
 block. All arguments after the module name in an inline definition represent
 "inline arguments". They are passed to the module instance directly and not
 used anyhow by other code (i.e. they are not guaranteed to be unique).
 
 ### A word on error logging
 
-Shortly put, it is module responsibility to log errors it generated since it is
+Shortly put, it is a module's responsibility to log errors it generated since it
-assumed it can provide all useful details about possible causes.
+is assumed it can provide all useful details about possible causes.
 
 Modules should not log errors received from other modules. However, it is 
 fine to log decisions made based on these errors.
@@ -92,9 +92,11 @@ fine to log decisions made based on these errors.
 This does not apply to "debug log", anything can be logged using it if it is
 considered useful for troubleshooting.
 
-Here is the example: remote module logs all errors received from remote server
+Here is the example: remote module logs all errors received from the remote
-and passes them to the caller. queue module only logs whether delivery to
+server and passes them to the caller. Queue module only logs whether delivery to
-certain recipient is permanently failed or it will be retried. When used
+the certain recipient is permanently failed or it will be retried. When used
 together, remote module will provide logs about concrete errors happened and
 queue module will provide information about tries made and scheduled to be made
-in future.
+in the future.
+
+[1]: https://github.com/foxcpp/maddy/wiki/Dev:-Comments-on-design

README.md

@@ -4,10 +4,11 @@
 
 Simple, fast, secure all-in-one mail server.
 
-**⚠️ Disclaimer: maddy is in early development, many planned features are missing and bugs are waiting to eat your messages**
+**⚠️ Disclaimer: maddy is in early development, many planned features are
+missing and bugs are waiting to eat your messages**
 
-Join [##maddy on irc.freenode.net](https://webchat.freenode.net/##maddy), if you have
+Join [##maddy on irc.freenode.net](https://webchat.freenode.net/##maddy), if you
-any questions or just want to talk about maddy.
+have any questions or just want to talk about maddy.
 
 ## Table of contents
 
@@ -32,7 +33,8 @@ any questions or just want to talk about maddy.
 - [MTA-STS](https://www.hardenize.com/blog/mta-sts) support
 - DNS sanity checks for incoming deliveries
 - Built-in [DKIM](https://blog.returnpath.com/how-to-explain-dkim-in-plain-english-2/) verification support
-- [Subaddressing](https://en.wikipedia.org/wiki/Email_address#Sub-addressing) (aka plus-addressing) support
+- [Subaddressing](https://en.wikipedia.org/wiki/Email_address#Sub-addressing)
+  (aka plus-addressing) support
 
 Planned features:
 - Built-in [DKIM](https://blog.returnpath.com/how-to-explain-dkim-in-plain-english-2/) signing
@@ -46,7 +48,8 @@ Planned features:
 
 ## Installation
 
-Pre-built binaries for releases are available [here](https://github.com/foxcpp/maddy/releases).
+Pre-built binaries for releases are available
+[here](https://github.com/foxcpp/maddy/releases).
 
 ## Building from source
 
@@ -66,20 +69,22 @@ Pre-built binaries for releases are available [here](https://github.com/foxcpp/m
   
 - C compiler (**optional**, set CGO_ENABLED env. variable to 0 to disable)
 
-  Required for SQLite3-based storage (default configuration) and PAM authentication.
+  Required for SQLite3-based storage (default configuration) and PAM
-  SQLite3 support can be disabled using nosqlite3 build tag:
+  authentication. SQLite3 support can be disabled using nosqlite3 build tag:
   ```
   GO111MODULE=on go get github.com/foxcpp/maddy/cmd/maddy@master -tags 'nosqlite3' 
   ```
  
 - libpam (**optional**, not needed by default)
 
-  Used for PAM auth helper binary or direct PAM use, later is disabled by default 
+  Used for PAM auth helper binary or direct PAM use, later is disabled by
-  and can be enabled using 'libpam' build tag (e.g. `go get ... -tags 'libpam nosqlite3'`)
+  default and can be enabled using 'libpam' build tag
+  (e.g. `go get ... -tags 'libpam nosqlite3'`)
   
-**Note:** Main executable built with CGO_ENABLED=0 does not depend on any system library
+**Note:** Main executable built with CGO_ENABLED=0 does not depend on any system
-and can be moved freely between systems. Executable built without libpam but with CGO_ENABLED=1 (default)
+library and can be moved freely between systems. Executable built without libpam
-depends only on libc. Executable built with libpam depends on system libpam, obviously.
+but with CGO_ENABLED=1 (default) depends only on libc. Executable built with
+libpam depends on system libpam, obviously.
 
 ### Building
 
@@ -88,7 +93,7 @@ First, make sure Go Modules support is enabled:
 export GO111MODULE=on
 ```
 
-Command to build latest commit from master branch:
+Command to build latest commit from the master branch:
 ```
 go get github.com/foxcpp/maddy/cmd/maddy@master
 ```
@@ -105,17 +110,17 @@ $HOME/go/bin).
 
 ## Quick start
 
-You need to make sure configuration is placed in /etc/maddy/maddy.conf
+You need to make sure configuration is placed in /etc/maddy/maddy.conf (copy
-(copy maddy.conf from this repo) and also /var/lib/maddy and /run/maddy exist
+maddy.conf from this repo) and also /var/lib/maddy and /run/maddy exist and
-and writable.
+writable.
 
 Then, simply run the executable:
 ```
 maddy 
 ```
 
-You can specify custom locations for all directories and config file, so
+You can specify custom locations for all directories and config file, so here is
-here is no need to mess with directories in your system:
+no need to mess with directories in your system:
 ```
 maddy -config /maddy.conf -state /state -runtime /tmp 
 ```
@@ -123,14 +128,14 @@ maddy will create specified directories for you.
 
 ### systemd unit
 
-Alternatively, you can use the systemd unit file from [dist/](dist) directory in this repo.
+Alternatively, you can use the systemd unit file from [dist/](dist) directory in
-It will automatically set-up user account and directories. Additionally, it 
+this repo. It will automatically set-up user account and directories.
-will apply strict sandbox to maddy to ensure additional security.
+Additionally, it will apply strict sandbox to maddy to ensure additional
+security.
 
 You need a relatively new systemd version (235+) both of these things to work
-properly. Otherwise, you still have to manually create a user account and 
+properly. Otherwise, you still have to manually create a user account and the
-the state + runtime directories with read-write permissions for 
+state + runtime directories with read-write permissions for the maddy user. 
-the maddy user. 
 
 ## Configuration
 
@@ -149,7 +154,8 @@ You need to change the following directives to your values:
 
 With that configuration you will get the following:
 - SQLite-based storage for messages
-- Authentication using SQLite-based virtual users DB (see [maddyctl utility](#maddyctl-utility))
+- Authentication using SQLite-based virtual users DB
+  (see [maddyctl utility](#maddyctl-utility))
 - SMTP endpoint for incoming messages on 25 port.
 - SMTP Submission endpoint for messages from your users, on both 587 (STARTTLS) 
 and 465 (TLS) ports.
@@ -172,10 +178,11 @@ $(local_domains) = example.com example.org
 ```
 admin@example.com and admin@example.org will refer to the same mailbox.
 
-If you want to make them separate - add `auth_perdomain` and `storage_perdomain` directives
+If you want to make them separate - add `auth_perdomain` and `storage_perdomain`
-below.
+directives below.
 
-Note that it will require users to specify full address as username when logging in.
+Note that it will require users to specify the full address as a username when
+logging in.
 
 ## maddyctl utility
 
@@ -206,8 +213,8 @@ If that's not the case, provide `-config` and/or `-state` arguments
 
 ### PostgreSQL instead of SQLite
 
-If you want to use PostgreSQL instead of SQLite 3 (e.g. you want better access concurrency), here is 
+If you want to use PostgreSQL instead of SQLite 3 (e.g. you want better access
-what you need to do:
+concurrency), here is what you need to do:
 
 1. Install, configure and start PostgreSQL server
 
@@ -245,24 +252,22 @@ the [project wiki](https://github.com/foxcpp/maddy/wiki).
 
 ## System authentication helper binaries
 
-By default maddy is running as a unprivileged user, meaning it can't read
+By default maddy is running as an unprivileged user, meaning it can't read
 system account passwords. There are two options:
-- Run maddy as a privileged user instead (not recommended)
 
-This way you can use maddy without messing with helper binaries, but that
+##### Run maddy as a privileged user instead (not recommended):
-will also give maddy a little bit too many permissions.
 
-- Let maddy start privileged (setuid) helper binary to perform authentication
+This way you can use maddy without messing with helper binaries, but that also
+gives maddy too many permissions.
   
-Compile [cmd/maddy-pam-helper](cmd/maddy-pam-helper) and/or
+##### Let maddy start a privileged helper binary to perform authentication:
-[cmd/maddy-shadow-helper](cmd/maddy-shadow-helper).
 
-Put them into `/usr/lib/maddy` and make them setuid root (there are also other
+1. Compile [cmd/maddy-pam-helper](cmd/maddy-pam-helper) and/or
-more restrictive options, check README in the executable directories).
+   [cmd/maddy-shadow-helper](cmd/maddy-shadow-helper).
-
+2. Put them into `/usr/lib/maddy` and make them setuid root (there are also
-Add `use_helper` to `pam` or `shadow` configuration block in your config.
+   other more restrictive options, check README in the executable directories).
-
+3. Add `use_helper` to `pam` or `shadow` configuration block in your config.
-Modify systemd unit to use less strict sandbox and disable DynamicUser.
+4. Modify systemd unit to use less strict sandbox and disable DynamicUser.
 
 ## Contributing
 
@@ -270,4 +275,4 @@ See [.github/CONTRIBUTING.md](.github/CONTRIBUTING.md).
 
 ## License
 
-MIT. Just do whatever you want.
+The code is under MIT license. See [LICENSE](LICENSE) for more information.