some cleanup:

* do not jump back and forth between different arguments
* display the flags in a proper list
* add the missing STANDARDS section
* mark up ASN.1 type names
* and minor wording improvements

1 files changed, 61 insertions, 52 deletions

diff --git a/lib/libcrypto/man/CMS_compress.3 b/lib/libcrypto/man/CMS_compress.3
index 0b3b105c162..8948618d3a6 100644
--- a/lib/libcrypto/man/CMS_compress.3
+++ b/lib/libcrypto/man/CMS_compress.3
@@ -1,7 +1,24 @@
-.\" $OpenBSD: CMS_compress.3,v 1.4 2019/08/11 12:46:38 schwarze Exp $
+.\" $OpenBSD: CMS_compress.3,v 1.5 2019/08/15 11:42:53 schwarze Exp $
 .\" full merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400
 .\"
-.\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
+.\" This file is a derived work.
+.\" The changes are covered by the following Copyright and license:
+.\"
+.\" Copyright (c) 2019 Ingo Schwarze <schwarze@openbsd.org>
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.\" The original file was written by Dr. Stephen Henson <steve@openssl.org>.
 .\" Copyright (c) 2008 The OpenSSL Project.  All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
@@ -48,7 +65,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: August 11 2019 $
+.Dd $Mdocdate: August 15 2019 $
 .Dt CMS_COMPRESS 3
 .Os
 .Sh NAME
@@ -64,77 +81,67 @@
 .Fc
 .Sh DESCRIPTION
 .Fn CMS_compress
-creates and returns a CMS CompressedData structure.
+creates and returns a CMS
+.Vt CompressedData
+structure.
+.Pp
 .Fa comp_nid
 is the compression algorithm to use or
 .Dv NID_undef
-to use the default algorithm (zlib compression).
-.Fa in
-is the content to be compressed.
-.Fa flags
-is an optional set of flags.
-.Pp
-The only currently supported compression algorithm is zlib using the NID
-.Dv NID_zlib_compression .
-.Pp
-If zlib support is not compiled in, then
+to use the default algorithm.
+Currently, the default algorithm
+.Dv NID_zlib_compression
+is the only supported algorithm.
+If zlib support is not compiled in,
 .Fn CMS_compress
-will return an error.
+always returns an error.
 .Pp
-If the
-.Dv CMS_TEXT
-flag is set, MIME headers for type text/plain are prepended to the data.
+.Fa in
+provides the content to be compressed.
 .Pp
-Normally the supplied content is translated into MIME canonical format
-(as required by the S/MIME specifications); if
-.Dv CMS_BINARY
-is set, no translation occurs.
+Any of the following flags (OR'ed together) can be passed in the
+.Fa flags
+parameter:
+.Bl -tag -width Ds
+.It Dv CMS_TEXT
+Prepend MIME headers for type text/plain to the data.
+.It Dv CMS_BINARY
+Do not translate the supplied content into MIME canonical format,
+even though that is required by the S/MIME specifications.
 This option should be used if the supplied data is in binary format.
 Otherwise, the translation will corrupt it.
 If
 .Dv CMS_BINARY
-is set then
+is set,
 .Dv CMS_TEXT
 is ignored.
-.Pp
-If the
-.Dv CMS_STREAM
-flag is set, a partial
+.It Dv CMS_STREAM
+Return a partial
 .Vt CMS_ContentInfo
-structure is returned suitable for streaming I/O: no data is read from
-the BIO
+structure suitable for streaming I/O: no data is read from
 .Fa in .
-.Pp
-The compressed data is included in the
-.Vt CMS_ContentInfo
-structure unless
-.Dv CMS_DETACHED
-is set, in which case it is omitted.
-This is rarely used in practice and is not supported by
-.Xr SMIME_write_CMS 3 .
-.Pp
-If the flag
-.Dv CMS_STREAM
-is set, the returned
-.Vt CMS_ContentInfo
-structure is
-.Em not
-complete and outputting its contents via a function that does not
-properly finalize the
-.Vt CMS_ContentInfo
-structure will give unpredictable results.
-.Pp
 Several functions including
 .Xr SMIME_write_CMS 3 ,
 .Xr i2d_CMS_bio_stream 3 ,
-and
+or
 .Xr PEM_write_bio_CMS_stream 3
-finalize the structure.
-Alternatively finalization can be performed by obtaining the streaming
+can be used to finalize the structure.
+Alternatively, finalization can be performed by obtaining the streaming
 ASN1
 .Vt BIO
 directly using
 .Xr BIO_new_CMS 3 .
+Outputting the contents of the
+.Vt CMS_ContentInfo
+structure via a function that does not
+properly finalize it will give unpredictable results.
+.It Dv CMS_DETACHED
+Do not include the compressed data in the
+.Vt CMS_ContentInfo
+structure.
+This is rarely used in practice and is not supported by
+.Xr SMIME_write_CMS 3 .
+.El
 .Pp
 Additional compression parameters such as the zlib compression level
 cannot currently be set.
@@ -149,6 +156,8 @@ The error can be obtained from
 .Xr ERR_get_error 3 .
 .Sh SEE ALSO
 .Xr CMS_uncompress 3
+.Sh STANDARDS
+RFC 3274: Compressed Data Content Type for Cryptographic Message Syntax (CMS)
 .Sh HISTORY
 .Fn CMS_compress
 first appeared in OpenSSL 0.9.8h