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 5F93CA0562; Tue, 4 May 2021 11:59:28 +0200 (CEST) Received: from [217.70.189.124] (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 212BE40147; Tue, 4 May 2021 11:59:28 +0200 (CEST) Received: from wout1-smtp.messagingengine.com (wout1-smtp.messagingengine.com [64.147.123.24]) by mails.dpdk.org (Postfix) with ESMTP id 0F46140141 for ; Tue, 4 May 2021 11:59:27 +0200 (CEST) Received: from compute4.internal (compute4.nyi.internal [10.202.2.44]) by mailout.west.internal (Postfix) with ESMTP id 882211BD8; Tue, 4 May 2021 05:59:24 -0400 (EDT) Received: from mailfrontend1 ([10.202.2.162]) by compute4.internal (MEProxy); Tue, 04 May 2021 05:59:25 -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= ddCv2S725iTlWARZEegSCpcHqT1G4NPHdbI62+QT+Us=; b=Z+eW2aAyzkjarTpo HtevT4TTbty/05dCBuBeDPQ6uWQObjLXHrWGuOPX5zEi6vZymn32TU41Beep19hf qMYd3NSKuo8hPgAZgsBasOShMFa7J6D7h7YQ7UYhnKVLvukknXu64eBtfBxG14Lc NM5V3RNUC6aVO2oeVUztn7sawK0EMGcsvOKPMzz2X4w1STshdogn5LpRN8U/3+fk 7QRHIkqb+Y43xFwwuj0CBt4zIlwfvV5jQ/Ry4YaVSbLOGYiQBeEo76bZvctWeJdO XjBPuQUltGkvDb9iwssZDydThOAPcNByNqsjCKimCskFNavmtPmnvgDqtF62L4wE I8HgMg== 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=ddCv2S725iTlWARZEegSCpcHqT1G4NPHdbI62+QT+ Us=; b=Ir8mwQBTp1gcKdn6ltnRDamYmw/9YeAovXGeM9LPUz8CArAJNj3IBxLiN 5oMXofF2jgnGeZrwedXiKzON+RjY2cQofv+RBvxk8DduJKGdbpPd7YcwyymgE5F9 ul7E42yGx2k4pwzpDLeqQJ6LAehT/PoGTA5JLS8soziVti+mvsQBta+cVJZLyrTa I4IumzpAfTDusrjG89rXafoRd+EzDVIuuNW6t415BSJNiGEyzsMjMGvqTft+R36M Sta0j8T1WMD1MHWhP2lp+2ErlSbsduILUOSOnCAzBZF2Ix2O41ujp0TAWKOTWMKb cWkxQehGFXlPPpw+RCHarBkHXb7kw== X-ME-Sender: X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgeduledrvdefiedgvdegucetufdoteggodetrfdotf fvucfrrhhofhhilhgvmecuhfgrshhtofgrihhlpdfqfgfvpdfurfetoffkrfgpnffqhgen uceurghilhhouhhtmecufedttdenucesvcftvggtihhpihgvnhhtshculddquddttddmne cujfgurhephffvufffkfgjfhgggfgtsehtufertddttddvnecuhfhrohhmpefvhhhomhgr shcuofhonhhjrghlohhnuceothhhohhmrghssehmohhnjhgrlhhonhdrnhgvtheqnecugg ftrfgrthhtvghrnhepudeggfdvfeduffdtfeeglefghfeukefgfffhueejtdetuedtjeeu ieeivdffgeehnecukfhppeejjedrudefgedrvddtfedrudekgeenucevlhhushhtvghruf hiiigvpedtnecurfgrrhgrmhepmhgrihhlfhhrohhmpehthhhomhgrshesmhhonhhjrghl ohhnrdhnvght 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; Tue, 4 May 2021 05:59:22 -0400 (EDT) From: Thomas Monjalon To: Conor Walsh , "Burakov, Anatoly" Cc: john.mcnamara@intel.com, david.marchand@redhat.com, ferruh.yigit@intel.com, bruce.richardson@intel.com, dev@dpdk.org Date: Tue, 04 May 2021 11:59:20 +0200 Message-ID: <2990415.rrcYuhbhSC@thomas> In-Reply-To: References: <20210421091146.1384708-1-conor.walsh@intel.com> <2242028.kHp4AaGxEa@thomas> 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" 04/05/2021 11:32, Burakov, Anatoly: > On 03-May-21 10:02 PM, Thomas Monjalon wrote: > > 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 > > Not having markup will 1) risk people accidentally "fixing" or otherwise > modifying comments, and 2) has bigger potential for collisions elsewhere > in the comments. While these aren't big risks, IMO it should be > explicitly obvious that a comment is not just a comment but a marker docs. > > Having named tags like in the original proposal is the most explicit > version of the above, which is why i favor it, but i think it's OK to > have a lighter-weight syntax (e.g. with scissors for example), however i > don't think it's a good idea to leave things implicit like your last > suggestion. I think the first comment is not only for code extraction, but also for code reader, that's why I think it's good to keep it natural.