From 2d8ab403cab39ce5844295a80c127c564fd61956 Mon Sep 17 00:00:00 2001 From: Steve Gerbino Date: Thu, 12 Mar 2026 18:07:48 +0100 Subject: [PATCH] Fix NOTE admonitions to include code snippets The single-line NOTE: shorthand only captures one line of text, leaving the code block rendered outside the admonition. Use the block form [NOTE]/==== to wrap the code snippet inside. --- doc/modules/ROOT/pages/3.tutorials/3a.echo-server.adoc | 5 ++++- doc/modules/ROOT/pages/3.tutorials/3b.http-client.adoc | 5 ++++- doc/modules/ROOT/pages/3.tutorials/3c.dns-lookup.adoc | 5 ++++- doc/modules/ROOT/pages/3.tutorials/3d.tls-context.adoc | 5 ++++- doc/modules/ROOT/pages/4.guide/4c.io-context.adoc | 5 ++++- doc/modules/ROOT/pages/4.guide/4d.sockets.adoc | 5 ++++- doc/modules/ROOT/pages/4.guide/4e.tcp-acceptor.adoc | 5 ++++- doc/modules/ROOT/pages/4.guide/4f.endpoints.adoc | 5 ++++- doc/modules/ROOT/pages/4.guide/4g.composed-operations.adoc | 5 ++++- doc/modules/ROOT/pages/4.guide/4h.timers.adoc | 5 ++++- doc/modules/ROOT/pages/4.guide/4i.signals.adoc | 5 ++++- doc/modules/ROOT/pages/4.guide/4j.resolver.adoc | 5 ++++- doc/modules/ROOT/pages/4.guide/4k.tcp-server.adoc | 5 ++++- doc/modules/ROOT/pages/4.guide/4l.tls.adoc | 5 ++++- doc/modules/ROOT/pages/4.guide/4m.error-handling.adoc | 5 ++++- doc/modules/ROOT/pages/4.guide/4n.buffers.adoc | 5 ++++- doc/modules/ROOT/pages/5.testing/5a.mocket.adoc | 5 ++++- doc/modules/ROOT/pages/quick-start.adoc | 5 ++++- 18 files changed, 72 insertions(+), 18 deletions(-) diff --git a/doc/modules/ROOT/pages/3.tutorials/3a.echo-server.adoc b/doc/modules/ROOT/pages/3.tutorials/3a.echo-server.adoc index 2f98dfe65..fd36752d9 100644 --- a/doc/modules/ROOT/pages/3.tutorials/3a.echo-server.adoc +++ b/doc/modules/ROOT/pages/3.tutorials/3a.echo-server.adoc @@ -13,7 +13,9 @@ This tutorial builds a production-quality echo server using the `tcp_server` framework. We'll explore worker pools, connection lifecycle, and the launcher pattern. -NOTE: Code snippets assume: +[NOTE] +==== +Code snippets assume: [source,cpp] ---- #include @@ -23,6 +25,7 @@ NOTE: Code snippets assume: namespace corosio = boost::corosio; namespace capy = boost::capy; ---- +==== == Overview diff --git a/doc/modules/ROOT/pages/3.tutorials/3b.http-client.adoc b/doc/modules/ROOT/pages/3.tutorials/3b.http-client.adoc index f1ace7140..97df9dbcd 100644 --- a/doc/modules/ROOT/pages/3.tutorials/3b.http-client.adoc +++ b/doc/modules/ROOT/pages/3.tutorials/3b.http-client.adoc @@ -13,7 +13,9 @@ This tutorial builds a simple HTTP client that connects to a server, sends a GET request, and reads the response. You'll learn socket connection, composed I/O operations, and the exception-based error handling pattern. -NOTE: Code snippets assume: +[NOTE] +==== +Code snippets assume: [source,cpp] ---- #include @@ -26,6 +28,7 @@ NOTE: Code snippets assume: namespace corosio = boost::corosio; namespace capy = boost::capy; ---- +==== == Overview diff --git a/doc/modules/ROOT/pages/3.tutorials/3c.dns-lookup.adoc b/doc/modules/ROOT/pages/3.tutorials/3c.dns-lookup.adoc index 57a846c01..793906fcf 100644 --- a/doc/modules/ROOT/pages/3.tutorials/3c.dns-lookup.adoc +++ b/doc/modules/ROOT/pages/3.tutorials/3c.dns-lookup.adoc @@ -13,7 +13,9 @@ This tutorial builds a command-line DNS lookup tool similar to `nslookup`. You'll learn to use the asynchronous resolver to convert hostnames to IP addresses. -NOTE: Code snippets assume: +[NOTE] +==== +Code snippets assume: [source,cpp] ---- #include @@ -23,6 +25,7 @@ NOTE: Code snippets assume: namespace corosio = boost::corosio; namespace capy = boost::capy; ---- +==== == Overview diff --git a/doc/modules/ROOT/pages/3.tutorials/3d.tls-context.adoc b/doc/modules/ROOT/pages/3.tutorials/3d.tls-context.adoc index a1e44ff8d..c2454b28f 100644 --- a/doc/modules/ROOT/pages/3.tutorials/3d.tls-context.adoc +++ b/doc/modules/ROOT/pages/3.tutorials/3d.tls-context.adoc @@ -13,13 +13,16 @@ This tutorial covers how to configure TLS contexts for secure connections. A `tls_context` stores certificates, keys, and settings that define how TLS connections are established and verified. -NOTE: Code snippets assume: +[NOTE] +==== +Code snippets assume: [source,cpp] ---- #include namespace tls = boost::corosio::tls; ---- +==== == Introduction diff --git a/doc/modules/ROOT/pages/4.guide/4c.io-context.adoc b/doc/modules/ROOT/pages/4.guide/4c.io-context.adoc index 3087f32c9..07e788e56 100644 --- a/doc/modules/ROOT/pages/4.guide/4c.io-context.adoc +++ b/doc/modules/ROOT/pages/4.guide/4c.io-context.adoc @@ -13,12 +13,15 @@ The `io_context` class is the heart of Corosio. It's an event loop that processes asynchronous I/O operations, manages timers, and coordinates coroutine execution. -NOTE: Code snippets assume: +[NOTE] +==== +Code snippets assume: [source,cpp] ---- #include namespace corosio = boost::corosio; ---- +==== == Overview diff --git a/doc/modules/ROOT/pages/4.guide/4d.sockets.adoc b/doc/modules/ROOT/pages/4.guide/4d.sockets.adoc index 1c3c466fe..29f6d0cca 100644 --- a/doc/modules/ROOT/pages/4.guide/4d.sockets.adoc +++ b/doc/modules/ROOT/pages/4.guide/4d.sockets.adoc @@ -13,7 +13,9 @@ The `tcp_socket` class provides asynchronous TCP networking. It supports connecting to servers, reading and writing data, and graceful connection management. -NOTE: Code snippets assume: +[NOTE] +==== +Code snippets assume: [source,cpp] ---- #include @@ -23,6 +25,7 @@ NOTE: Code snippets assume: namespace corosio = boost::corosio; namespace capy = boost::capy; ---- +==== == Overview diff --git a/doc/modules/ROOT/pages/4.guide/4e.tcp-acceptor.adoc b/doc/modules/ROOT/pages/4.guide/4e.tcp-acceptor.adoc index d76a2d07d..059fdef40 100644 --- a/doc/modules/ROOT/pages/4.guide/4e.tcp-acceptor.adoc +++ b/doc/modules/ROOT/pages/4.guide/4e.tcp-acceptor.adoc @@ -12,7 +12,9 @@ The `tcp_acceptor` class listens for incoming TCP connections and accepts them into socket objects. It's the foundation for building TCP servers. -NOTE: Code snippets assume: +[NOTE] +==== +Code snippets assume: [source,cpp] ---- #include @@ -21,6 +23,7 @@ NOTE: Code snippets assume: namespace corosio = boost::corosio; ---- +==== == Overview diff --git a/doc/modules/ROOT/pages/4.guide/4f.endpoints.adoc b/doc/modules/ROOT/pages/4.guide/4f.endpoints.adoc index 40b0f2971..f839ac0f6 100644 --- a/doc/modules/ROOT/pages/4.guide/4f.endpoints.adoc +++ b/doc/modules/ROOT/pages/4.guide/4f.endpoints.adoc @@ -13,7 +13,9 @@ The `endpoint` class represents a network endpoint: an IP address (IPv4 or IPv6) combined with a port number. Endpoints are used for connecting sockets and binding acceptors. -NOTE: Code snippets assume: +[NOTE] +==== +Code snippets assume: [source,cpp] ---- #include @@ -22,6 +24,7 @@ NOTE: Code snippets assume: namespace corosio = boost::corosio; ---- +==== == Overview diff --git a/doc/modules/ROOT/pages/4.guide/4g.composed-operations.adoc b/doc/modules/ROOT/pages/4.guide/4g.composed-operations.adoc index bd9e57fea..41de82220 100644 --- a/doc/modules/ROOT/pages/4.guide/4g.composed-operations.adoc +++ b/doc/modules/ROOT/pages/4.guide/4g.composed-operations.adoc @@ -12,7 +12,9 @@ Corosio provides composed operations that build on the primitive `read_some()` and `write_some()` functions to provide higher-level guarantees. -NOTE: Code snippets assume: +[NOTE] +==== +Code snippets assume: [source,cpp] ---- #include @@ -22,6 +24,7 @@ NOTE: Code snippets assume: namespace corosio = boost::corosio; namespace capy = boost::capy; ---- +==== == The Problem with Primitives diff --git a/doc/modules/ROOT/pages/4.guide/4h.timers.adoc b/doc/modules/ROOT/pages/4.guide/4h.timers.adoc index 62b2d95e6..3c2bc6a70 100644 --- a/doc/modules/ROOT/pages/4.guide/4h.timers.adoc +++ b/doc/modules/ROOT/pages/4.guide/4h.timers.adoc @@ -14,13 +14,16 @@ The `timer` class provides asynchronous delays and timeouts. It integrates with the I/O context to schedule operations at specific times or after durations. -NOTE: Code snippets assume: +[NOTE] +==== +Code snippets assume: [source,cpp] ---- #include namespace corosio = boost::corosio; using namespace std::chrono_literals; ---- +==== == Overview diff --git a/doc/modules/ROOT/pages/4.guide/4i.signals.adoc b/doc/modules/ROOT/pages/4.guide/4i.signals.adoc index 5b43b3b02..6f953a821 100644 --- a/doc/modules/ROOT/pages/4.guide/4i.signals.adoc +++ b/doc/modules/ROOT/pages/4.guide/4i.signals.adoc @@ -13,7 +13,9 @@ The `signal_set` class provides asynchronous signal handling. It allows coroutines to wait for operating system signals like SIGINT (Ctrl+C) or SIGTERM. -NOTE: Code snippets assume: +[NOTE] +==== +Code snippets assume: [source,cpp] ---- #include @@ -21,6 +23,7 @@ NOTE: Code snippets assume: namespace corosio = boost::corosio; ---- +==== == Overview diff --git a/doc/modules/ROOT/pages/4.guide/4j.resolver.adoc b/doc/modules/ROOT/pages/4.guide/4j.resolver.adoc index 1b7dff28d..79b792148 100644 --- a/doc/modules/ROOT/pages/4.guide/4j.resolver.adoc +++ b/doc/modules/ROOT/pages/4.guide/4j.resolver.adoc @@ -13,12 +13,15 @@ The `resolver` class performs asynchronous DNS lookups, converting hostnames to IP addresses. It wraps the system's `getaddrinfo()` function with an asynchronous interface. -NOTE: Code snippets assume: +[NOTE] +==== +Code snippets assume: [source,cpp] ---- #include namespace corosio = boost::corosio; ---- +==== == Overview diff --git a/doc/modules/ROOT/pages/4.guide/4k.tcp-server.adoc b/doc/modules/ROOT/pages/4.guide/4k.tcp-server.adoc index ed0dc7804..d5b220482 100644 --- a/doc/modules/ROOT/pages/4.guide/4k.tcp-server.adoc +++ b/doc/modules/ROOT/pages/4.guide/4k.tcp-server.adoc @@ -13,7 +13,9 @@ The `tcp_server` class provides a framework for building TCP servers with connection pooling. It manages acceptors, worker pools, and connection lifecycle automatically. -NOTE: Code snippets assume: +[NOTE] +==== +Code snippets assume: [source,cpp] ---- #include @@ -23,6 +25,7 @@ NOTE: Code snippets assume: namespace corosio = boost::corosio; namespace capy = boost::capy; ---- +==== == Overview diff --git a/doc/modules/ROOT/pages/4.guide/4l.tls.adoc b/doc/modules/ROOT/pages/4.guide/4l.tls.adoc index 8659ca8c9..d85efd01e 100644 --- a/doc/modules/ROOT/pages/4.guide/4l.tls.adoc +++ b/doc/modules/ROOT/pages/4.guide/4l.tls.adoc @@ -13,7 +13,9 @@ Corosio provides TLS encryption through the `tls_context` configuration class and stream wrappers that add encryption to existing connections. This chapter covers context configuration, stream usage, and common TLS patterns. -NOTE: Code snippets assume: +[NOTE] +==== +Code snippets assume: [source,cpp] ---- #include @@ -23,6 +25,7 @@ NOTE: Code snippets assume: namespace corosio = boost::corosio; namespace tls = corosio::tls; ---- +==== == Overview diff --git a/doc/modules/ROOT/pages/4.guide/4m.error-handling.adoc b/doc/modules/ROOT/pages/4.guide/4m.error-handling.adoc index 2d637619d..e2e77e4ad 100644 --- a/doc/modules/ROOT/pages/4.guide/4m.error-handling.adoc +++ b/doc/modules/ROOT/pages/4.guide/4m.error-handling.adoc @@ -12,7 +12,9 @@ Corosio provides flexible error handling through the `io_result` type, which supports both error-code and exception-based patterns. -NOTE: Code snippets assume: +[NOTE] +==== +Code snippets assume: [source,cpp] ---- #include @@ -22,6 +24,7 @@ NOTE: Code snippets assume: namespace corosio = boost::corosio; namespace capy = boost::capy; ---- +==== == The io_result Type diff --git a/doc/modules/ROOT/pages/4.guide/4n.buffers.adoc b/doc/modules/ROOT/pages/4.guide/4n.buffers.adoc index 1f08cc350..3b16ae17d 100644 --- a/doc/modules/ROOT/pages/4.guide/4n.buffers.adoc +++ b/doc/modules/ROOT/pages/4.guide/4n.buffers.adoc @@ -12,12 +12,15 @@ Corosio I/O operations work with buffer sequences from Boost.Capy. This page explains how to use buffers effectively. -NOTE: Code snippets assume: +[NOTE] +==== +Code snippets assume: [source,cpp] ---- #include namespace capy = boost::capy; ---- +==== == Buffer Types diff --git a/doc/modules/ROOT/pages/5.testing/5a.mocket.adoc b/doc/modules/ROOT/pages/5.testing/5a.mocket.adoc index cca81b285..850633e84 100644 --- a/doc/modules/ROOT/pages/5.testing/5a.mocket.adoc +++ b/doc/modules/ROOT/pages/5.testing/5a.mocket.adoc @@ -13,7 +13,9 @@ The `mocket` class provides mock sockets for testing I/O code without actual network operations. Mockets let you stage data for reading and verify expected writes. -NOTE: Code snippets assume: +[NOTE] +==== +Code snippets assume: [source,cpp] ---- #include @@ -22,6 +24,7 @@ NOTE: Code snippets assume: namespace corosio = boost::corosio; namespace capy = boost::capy; ---- +==== == Overview diff --git a/doc/modules/ROOT/pages/quick-start.adoc b/doc/modules/ROOT/pages/quick-start.adoc index 6cd16d429..6993878c2 100644 --- a/doc/modules/ROOT/pages/quick-start.adoc +++ b/doc/modules/ROOT/pages/quick-start.adoc @@ -13,7 +13,9 @@ This guide walks you through building your first network application with Corosio: a simple echo server that accepts connections and echoes back whatever clients send. -NOTE: Code snippets assume: +[NOTE] +==== +Code snippets assume: [source,cpp] ---- #include @@ -23,6 +25,7 @@ NOTE: Code snippets assume: namespace corosio = boost::corosio; namespace capy = boost::capy; ---- +==== == Step 1: Create the I/O Context