From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124]) by inbox.dpdk.org (Postfix) with ESMTP id 65290A0562; Mon, 3 May 2021 23:02:22 +0200 (CEST) Received: from [217.70.189.124] (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id DFA0940150; Mon, 3 May 2021 23:02:21 +0200 (CEST) Received: from wout4-smtp.messagingengine.com (wout4-smtp.messagingengine.com [64.147.123.20]) by mails.dpdk.org (Postfix) with ESMTP id B1BF24014E for ; Mon, 3 May 2021 23:02:20 +0200 (CEST) Received: from compute3.internal (compute3.nyi.internal [10.202.2.43]) by mailout.west.internal (Postfix) with ESMTP id 1EBC71F3A; Mon, 3 May 2021 17:02:19 -0400 (EDT) Received: from mailfrontend1 ([10.202.2.162]) by compute3.internal (MEProxy); Mon, 03 May 2021 17:02:19 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=monjalon.net; h= from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding:content-type; s=fm1; bh= pnncI+usurOBrTXldob/Vg/s0fJgnoyg42VsKijPGy4=; b=mS7E837fg1ILUAF/ fvvVsiJa3iPB9Gje6pnXLM4CctR/kZQTCB3zTsCjoBl3znEN/Cm82VRKDgCz6e3b 6C52V6E/mEerjIFmj4VFX5DH1t1E0Yub95IYcmv3pplo8G9izE5Iz1Ad2+ua33Rf uD79mVDNpYY9a+7+JkC7ziWGEKt+XGdRAHHP97+r1gUIk0/RZebeVORrSGwr7tGU /UfwlwBQXLh/JfAzwMoXSIvMzVguHCiaSslAFPXCIgSTFcHq4CDm+CidVaC6plGX rllN+ozsBiSWhw7W6VkOIxBCECBHpoG0xWetUQAbQvlrQvD1f/YNIXhTklxKqZ5o za9PZQ== DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= messagingengine.com; h=cc:content-transfer-encoding:content-type :date:from:in-reply-to:message-id:mime-version:references :subject:to:x-me-proxy:x-me-proxy:x-me-sender:x-me-sender :x-sasl-enc; s=fm2; bh=pnncI+usurOBrTXldob/Vg/s0fJgnoyg42VsKijPG y4=; b=Xl/T2IIUhOT5sOyEr9ReLXfbfBm/NXYnNNliHJi+1YfT93lEQgJpLQ6fL TwOi+6KVP238DGdeBrVInrZ+uNRMRbB7NkkFC2Ei21bk7NU2+J0k0Ri6sweRqoXB qOoUNl2au2aqDFHsqADanwRln9q+ToaVrhJ1l2nsoDtEX+ZFU6LkWf6iY7n8r03H olUMbN+u974EXhlVIruc1TkIrEPiRljPpOUUK87d8gouEoi6GePOfcCvx43tPjHX QB7dlitBa7vu/siVAYKDMeH23gKn5dTwqS7EfP3q1uSdY64p9AGvjOSfwW4niRsX 7H03H4yp2dICF8JCWCY9QDOxb3CCw== X-ME-Sender: X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgeduledrvdefgedgudehkecutefuodetggdotefrod ftvfcurfhrohhfihhlvgemucfhrghsthforghilhdpqfgfvfdpuffrtefokffrpgfnqfgh necuuegrihhlohhuthemuceftddtnecusecvtfgvtghiphhivghnthhsucdlqddutddtmd enucfjughrpefhvffufffkjghfggfgtgesthfuredttddtvdenucfhrhhomhepvfhhohhm rghsucfoohhnjhgrlhhonhcuoehthhhomhgrshesmhhonhhjrghlohhnrdhnvghtqeenuc ggtffrrghtthgvrhhnpedugefgvdefudfftdefgeelgffhueekgfffhfeujedtteeutdej ueeiiedvffegheenucfkphepjeejrddufeegrddvtdefrddukeegnecuvehluhhsthgvrh fuihiivgeptdenucfrrghrrghmpehmrghilhhfrhhomhepthhhohhmrghssehmohhnjhgr lhhonhdrnhgvth X-ME-Proxy: Received: from xps.localnet (184.203.134.77.rev.sfr.net [77.134.203.184]) by mail.messagingengine.com (Postfix) with ESMTPA; Mon, 3 May 2021 17:02:17 -0400 (EDT) From: Thomas Monjalon To: Conor Walsh Cc: john.mcnamara@intel.com, david.marchand@redhat.com, ferruh.yigit@intel.com, bruce.richardson@intel.com, anatoly.burakov@intel.com, dev@dpdk.org Date: Mon, 03 May 2021 23:02:14 +0200 Message-ID: <2242028.kHp4AaGxEa@thomas> In-Reply-To: <20210421091146.1384708-1-conor.walsh@intel.com> References: <20210421091146.1384708-1-conor.walsh@intel.com> MIME-Version: 1.0 Content-Transfer-Encoding: 7Bit Content-Type: text/plain; charset="us-ascii" Subject: Re: [dpdk-dev] [PATCH] doc/contributing/documentation: add info about including code X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org Sender: "dev" 21/04/2021 11:11, Conor Walsh: > + The following will include a snippet from the skeleton sample app:: > + > + .. literalinclude:: ../../../examples/skeleton/basicfwd.c > + :language: c > + :start-after: Display the port MAC address. > + :end-before: Enable RX in promiscuous mode for the Ethernet device. > + :dedent: 1 I would prefer indenting the options with 3 spaces to make them aligned with literalinclude. [...] > +* ``start-after`` and ``end-before`` can use any text within a given file, > + however it may be difficult to find unique text within your code to mark the > + start and end of your snippets. In these cases, it is recommended to include > + explicit tags in your code to denote these locations for documentation purposes. > + > + This can be done as follows: > + > + .. code-block:: c > + > + /* #guide_doc: Example feature being documented. */ > + ... > + /* #guide_doc: End of example feature being documented. */ I think we can standardize this usage in a beautiful syntax. My proposal, using the scissor sign: /* Foo bar >8 */ foo(bar); /* 8< End of foo bar */ .. literalinclude:: foobar.c :language: C :start-after: Foo bar >8 :end-before: 8< End of foo bar Another idea: /*~ Foo bar */ foo(bar); /*~ End of foo bar */ .. literalinclude:: foobar.c :language: C :start-after: ~ Foo bar :end-before: ~ End of foo bar Maybe we don't need any markup for the start line and keep it natural: /* Foo bar */ foo(bar); /* end: Foo bar */ .. literalinclude:: foobar.c :language: C :start-after: Foo bar :end-before: end: Foo bar