Artifactspublic-v0

curl

master
ply4 git calls405 ms289 KiB2 cachedprotocol v2
165 lines4.9 KiBRaw

curldown

A markdown-like syntax for libcurl man pages.

Purpose

A text format for writing libcurl documentation in the shape of man pages.

Make it easier for users to contribute and write documentation. A format that is easier on the eye in its source format.

Make it harder to do syntactical mistakes.

Use a format that allows creating man pages that end up looking exactly like the man pages did when we wrote them in nroff format.

Take advantage of the fact that people these days are accustomed to markdown by using a markdown-like syntax.

This allows us to fix issues in the nroff format easier since now we generate them. For example: escaping minus to prevent them from being turned into Unicode by man.

Generate nroff output that looks (next to) identical to the previous files, so that the look, existing test cases, HTML conversions, existing infrastructure etc remain mostly intact.

Contains meta-data in a structured way to allow better output (for example the see also information) and general awareness of what the file is about.

File extension

Since curldown looks similar to markdown, we use .md extensions on the files.

Conversion

Convert from curldown to nroff with cd2nroff. Generates nroff man pages.

Convert from nroff to curldown with nroff2cd. This is only meant to be used for the initial conversion to curldown and should ideally never be needed again.

Convert, check or clean up an existing curldown to nicer, better, cleaner curldown with cd2cd.

Mass-convert all curldown files to nroff in specified directories with cdall:

cdall [dir1] [dir2] [dir3] ..

Known issues

The cd2nroff tool does not yet handle italics or bold where the start and the end markers are used on separate lines.

The nroff2cd tool generates code style quotes for all .fi sections since the nroff format does not carry a distinction.

Format

Each curldown starts with a header with meta-data:

---
c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
SPDX-License-Identifier: curl
Title: CURLOPT_AWS_SIGV4
Section: 3
Source: libcurl
Protocol:
  - HTTP
See-also:
  - CURLOPT_HEADEROPT (3)
  - CURLOPT_HTTPAUTH (3)
TLS-backend:
  - [name]
Added-in: [version or "n/a"]
---

All curldown files must have all the headers present and at least one See-also: entry specified.

If the man page is for section 3 (library related). The Protocol list must contain at least one protocol, which can be * if the option is virtually for everything. If * is used, it must be the only listed protocol. Recognized protocols are either URL schemes (in uppercase), TLS or TCP.

If the Protocol list contains TLS, then there must also be a TLS-backend list, specifying All or a list of what TLS backends that work with this option. The available TLS backends are:

  • GnuTLS
  • mbedTLS
  • OpenSSL (also covers AmiSSL, AWS-LC, BoringSSL, LibreSSL and quictls)
  • rustls
  • Schannel
  • wolfSSL
  • All: all TLS backends

Following the header in the file, is the manual page using markdown-like syntax:

    # NAME
    a page - this is a page describing something

    # SYNOPSIS
    ~~~c
    #include <curl/curl.h>

    CURLcode curl_easy_setopt(CURL *handle, CURLOPT_AWS_SIGV4, char *param);
    ~~~

Quoted source code should start with ~~~c and end with ~~~ while regular quotes can start with ~~~ or be indented with 4 spaces.

Headers at top-level # get converted to .SH.

nroff2cd supports the ## next level header which gets converted to .IP.

Write bold words or phrases within ** like:

This is a **bold** word.

Write italics like:

This is *italics*.

Due to how man pages do not support backticks especially formatted, such occurrences in the source are instead using italics in the generated output:

This `word` appears in italics.

When generating the nroff output, the tooling removes superfluous newlines, meaning they can be used freely in the source file to make the text more readable.

To make sure curldown documents render correctly as markdown, all literal occurrences of < or > need to be escaped by a leading backslash.

Generating contents

# %PROTOCOLS% - inserts a PROTOCOLS section based on the metadata provided in the header.

# %AVAILABILITY% - inserts an AVAILABILITY section based on the metadata provided in the header.

Symbols

All mentioned curl symbols that have their own man pages, like curl_easy_perform(3) are automatically rendered using italics in the output without having to enclose it with asterisks. This helps ensuring that they get converted to links properly later in the HTML version on the website, as converted with roffit. This makes the curldown text easier to read even when mentioning many curl symbols.

This auto-linking works for patterns matching (lib|)curl[^ ]*(3).

1<!--
2Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
4SPDX-License-Identifier: curl
5-->
7# curldown
9A markdown-like syntax for libcurl man pages.
11## Purpose
13A text format for writing libcurl documentation in the shape of man pages.
15Make it easier for users to contribute and write documentation. A format that
16is easier on the eye in its source format.
18Make it harder to do syntactical mistakes.
20Use a format that allows creating man pages that end up looking exactly like
21the man pages did when we wrote them in nroff format.
23Take advantage of the fact that people these days are accustomed to markdown
24by using a markdown-like syntax.
26This allows us to fix issues in the nroff format easier since now we generate
27them. For example: escaping minus to prevent them from being turned into
28Unicode by man.
30Generate nroff output that looks (next to) *identical* to the previous files,
31so that the look, existing test cases, HTML conversions, existing
32infrastructure etc remain mostly intact.
34Contains meta-data in a structured way to allow better output (for example the
35see also information) and general awareness of what the file is about.
37## File extension
39Since curldown looks similar to markdown, we use `.md` extensions on the
40files.
42## Conversion
44Convert **from curldown to nroff** with `cd2nroff`. Generates nroff man pages.
46Convert **from nroff to curldown** with `nroff2cd`. This is only meant to be
47used for the initial conversion to curldown and should ideally never be needed
48again.
50Convert, check or clean up an existing curldown to nicer, better, cleaner
51curldown with **cd2cd**.
53Mass-convert all curldown files to nroff in specified directories with
54`cdall`:
56 cdall [dir1] [dir2] [dir3] ..
58## Known issues
60The `cd2nroff` tool does not yet handle *italics* or **bold** where the start
61and the end markers are used on separate lines.
63The `nroff2cd` tool generates code style quotes for all `.fi` sections since
64the nroff format does not carry a distinction.
66# Format
68Each curldown starts with a header with meta-data:
70 ---
71 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
72 SPDX-License-Identifier: curl
73 Title: CURLOPT_AWS_SIGV4
74 Section: 3
75 Source: libcurl
76 Protocol:
77 - HTTP
78 See-also:
79 - CURLOPT_HEADEROPT (3)
80 - CURLOPT_HTTPAUTH (3)
81 TLS-backend:
82 - [name]
83 Added-in: [version or "n/a"]
84 ---
86All curldown files *must* have all the headers present and at least one
87`See-also:` entry specified.
89If the man page is for section 3 (library related). The `Protocol` list must
90contain at least one protocol, which can be `*` if the option is virtually for
91everything. If `*` is used, it must be the only listed protocol. Recognized
92protocols are either URL schemes (in uppercase), `TLS` or `TCP`.
94If the `Protocol` list contains `TLS`, then there must also be a `TLS-backend`
95list, specifying `All` or a list of what TLS backends that work with this
96option. The available TLS backends are:
98- `GnuTLS`
99- `mbedTLS`
100- `OpenSSL` (also covers AmiSSL, AWS-LC, BoringSSL, LibreSSL and quictls)
101- `rustls`
102- `Schannel`
103- `wolfSSL`
104- `All`: all TLS backends
106Following the header in the file, is the manual page using markdown-like
107syntax:
109~~~
110 # NAME
111 a page - this is a page describing something
113 # SYNOPSIS
114 ~~~c
115 #include <curl/curl.h>
117 CURLcode curl_easy_setopt(CURL *handle, CURLOPT_AWS_SIGV4, char *param);
118 ~~~
119~~~
121Quoted source code should start with `~~~c` and end with `~~~` while regular
122quotes can start with `~~~` or be indented with 4 spaces.
124Headers at top-level `#` get converted to `.SH`.
126`nroff2cd` supports the `##` next level header which gets converted to `.IP`.
128Write bold words or phrases within `**` like:
130 This is a **bold** word.
132Write italics like:
134 This is *italics*.
136Due to how man pages do not support backticks especially formatted, such
137occurrences in the source are instead using italics in the generated output:
139 This `word` appears in italics.
141When generating the nroff output, the tooling removes superfluous newlines,
142meaning they can be used freely in the source file to make the text more
143readable.
145To make sure curldown documents render correctly as markdown, all literal
146occurrences of `<` or `>` need to be escaped by a leading backslash.
148## Generating contents
150`# %PROTOCOLS%` - inserts a **PROTOCOLS** section based on the metadata
151provided in the header.
153`# %AVAILABILITY%` - inserts an **AVAILABILITY** section based on the metadata
154provided in the header.
156## Symbols
158All mentioned curl symbols that have their own man pages, like
159`curl_easy_perform(3)` are automatically rendered using italics in the output
160without having to enclose it with asterisks. This helps ensuring that they get
161converted to links properly later in the HTML version on the website, as
162converted with `roffit`. This makes the curldown text easier to read even when
163mentioning many curl symbols.
165This auto-linking works for patterns matching `(lib|)curl[^ ]*(3)`.
Diagnostics4 git calls · 405 ms
CallStatusSizeTime0405 ms
discover200152 B3 ms
git.upload-pack discover
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=2
git.response.bytes=152
git.server.agent=gitty/1.0
git.server.object_format=sha1
git.server.caps=agent ls-refs fetch object-format
git.server.fetch=shallow filter sideband-all
git.protocol.version=2
git.pkt.frames=8
git.pkt.data=6
git.pkt.flush=2
git.pkt.delim=0
git.pkt.bytes=152
git.pkt.payload.max=34
ls-refs200149 B · hit3 ms
git.upload-pack ls-refs
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=3
git.response.bytes=149
git.response.cache=HIT
git.response.duration_ms=3
git.protocol.version=2
git.pkt.frames=3
git.pkt.data=2
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=149
git.pkt.payload.max=78
git.ls_refs.count=2
git.ls_refs.head=refs/heads/master
fetchblob:none · deepen 10200287 KiB · hit2 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=400
git.response.bytes=293470
git.response.cache=HIT
git.response.duration_ms=2
git.fetch.filter=blob:none
git.fetch.filter.requested=tree:0
git.fetch.filter.fallback=blob:none
git.fetch.filter.learned=false
git.fetch.wants=31c911efe5652725e930f4d2e60c9060e5f6646d
git.fetch.haves.count=0
git.fetch.deepen=10
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=10
git.pkt.data=8
git.pkt.flush=1
git.pkt.delim=1
git.pkt.bytes=293470
git.pkt.payload.max=65516
git.sideband.band1.bytes=293354
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=87
git.pack.bytes=293354
git.pack.ofs_delta=0
git.pack.ref_delta=1
git.pack.chain.max=1
git.pack.trailer=6a646bcda6740bab42e321b51998b52ea15146c0
git.pack.full=86
Open pack map
fetch2002.4 KiB400 ms
git.upload-pack fetch
http.response.status_code=200
git.response.bytes=2453
git.response.cache=MISS
git.response.duration_ms=400
git.fetch.wants=c804eae746b27fd3ba9ec7342b3b54635c478594
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=3
git.pkt.data=2
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=2453
git.pkt.payload.max=2432
git.sideband.band1.bytes=2431
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0

Each row is one HTTP round trip ply made to the git server for this page, on one timeline. discover asks what the server speaks, ls-refs lists branch tips, fetch brings objects by id. A hit was served by Workers Cache. Tap a row for its wire details.

Remote
https://5ad2236b39de4c8bd8f6270ea63f3ea9.artifacts.cloudflare.net/git/public-v0/curl.git
Ref
refs/heads/master
Commit
31c911efe5652725e930f4d2e60c9060e5f6646d
cf-ray
a5e9e6cbce4aeefa
Request
fee427c6…
Protocol
v2 · sha1
Agent
gitty/1.0
Filter
advertised
Fetch
shallow filter sideband-all
Capabilities
agent ls-refs fetch object-format