From nobody Tue Jan 31 09:20:42 2023 X-Original-To: freebsd-doc@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 4P5ffx5gc7z3bwFn for ; Tue, 31 Jan 2023 09:20:57 +0000 (UTC) (envelope-from ceri@submonkey.net) Received: from mail-wm1-x334.google.com (mail-wm1-x334.google.com [IPv6:2a00:1450:4864:20::334]) (using TLSv1.3 with cipher TLS_AES_128_GCM_SHA256 (128/128 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (2048 bits) client-digest SHA256) (Client CN "smtp.gmail.com", Issuer "GTS CA 1D4" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4P5ffx1rfDz47sb for ; Tue, 31 Jan 2023 09:20:57 +0000 (UTC) (envelope-from ceri@submonkey.net) Authentication-Results: mx1.freebsd.org; none Received: by mail-wm1-x334.google.com with SMTP id iv8-20020a05600c548800b003db04a0a46bso529775wmb.0 for ; Tue, 31 Jan 2023 01:20:57 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=submonkey-net.20210112.gappssmtp.com; s=20210112; h=to:in-reply-to:cc:references:message-id:date:subject:mime-version :from:content-transfer-encoding:from:to:cc:subject:date:message-id :reply-to; bh=aNnV4WMxRlR82W6/4seUcnSL5Luu+aPfnSz7c2seNLM=; b=x0TBaUy88e4gyF5LoDdPrBLk8qCnpKjfO/KxO78V6Db6EatATAEtwEck0P83043dOj LUF4yr4p6t0ReE3agFdlwmczIgD0xxpm9r3tx1+wKtJi6fifA767b/QrEKEHX4uiJj5u GMblPa+cBu/uK7aPif2QxG6pmNg71Dobzxwo+mNfyqQkgV/IhmZn2qjhfa3bUBRrfOvX XFOTnMlYB1MR/zYqRoWL1NVR7KjpVVGCqMxs4sBFhPrbA5cuw2VCUFRCLQe1xBEj908v XwjPB2UYoC4WKx6qOeOglYVMUYQU5ogVvsF0FWHylz5aUlDKNkGxxq11vmbS0UUy/9OD uL3w== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=to:in-reply-to:cc:references:message-id:date:subject:mime-version :from:content-transfer-encoding:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=aNnV4WMxRlR82W6/4seUcnSL5Luu+aPfnSz7c2seNLM=; b=6fAvsdxrg8E0HAgYEgCy37fQRA/kl92hT8Lzg7k514W2vSeyN2tdVrStCPY7Uue86c 5YSGD8iSLY8MaTqGOdFhQMxMWIyNp6JRAhbROmkL0CRelg4wjW5tBwbgQmZtu9rO9MM4 3Li8QUyLRtfT/Fckc374yALUxp7V6cG8+Tp9vZmr2+NKwJI6n+gieIo9/cEfKpgsS4G3 d+4XWGfpSvlEmxW3uxeuACW9rAGCfxsnbLZr/Xf5oc2xnW0++nSW5Gu4klDW+7N/Ctyn X0ivPL+T+pvUd/BOV4B7bCD4B7sjvfw+/0yTPel+f1hrsp6twWYpGkgH4jjPRPe/epfR gjyQ== X-Gm-Message-State: AO0yUKX9OORWsOgJk/RSIFGObDz606XHt3LGZHAk6bBq57zc+aNUwRNu QoAtFekBLUZ5Lgi7xAJmM5dEDg== X-Google-Smtp-Source: AK7set/ojN4Llm/5+IhJGXC362f4aWhuPDQoIqRXZICKDQpEMP2sCKZK882LdTbUCJzC/OEsKStzVQ== X-Received: by 2002:a05:600c:3511:b0:3dc:58a2:38e3 with SMTP id h17-20020a05600c351100b003dc58a238e3mr7160137wmq.26.1675156854685; Tue, 31 Jan 2023 01:20:54 -0800 (PST) Received: from smtpclient.apple ([88.97.110.43]) by smtp.gmail.com with ESMTPSA id m42-20020a05600c092a00b003dc5abd2b4fsm4971141wmp.44.2023.01.31.01.20.53 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Tue, 31 Jan 2023 01:20:54 -0800 (PST) Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable From: Ceri Davies List-Id: Documentation project List-Archive: https://lists.freebsd.org/archives/freebsd-doc List-Help: List-Post: List-Subscribe: List-Unsubscribe: Sender: owner-freebsd-doc@freebsd.org Mime-Version: 1.0 (1.0) Subject: Re: To be deprecated [.filename]## tag in the document? Date: Tue, 31 Jan 2023 09:20:42 +0000 Message-Id: <2D12D689-A2F5-4C7E-8394-F12D7614707B@submonkey.net> References: <20230131080243.zsxwgvx6qxfjjdc3@aching.in.mat.cc> Cc: Sergio Carlavilla , doceng@freebsd.org, ykla , freebsd-doc@freebsd.org In-Reply-To: <20230131080243.zsxwgvx6qxfjjdc3@aching.in.mat.cc> To: Mathieu Arnold X-Mailer: iPhone Mail (20D47) X-Rspamd-Queue-Id: 4P5ffx1rfDz47sb X-Spamd-Bar: ---- X-Spamd-Result: default: False [-4.00 / 15.00]; REPLY(-4.00)[]; ASN(0.00)[asn:15169, ipnet:2a00:1450::/32, country:US] X-Rspamd-Pre-Result: action=no action; module=replies; Message is reply to one we originated X-ThisMailContainsUnwantedMimeParts: N > On 31 Jan 2023, at 08:02, Mathieu Arnold wrote: >=20 > =EF=BB=BFOn Mon, Jan 30, 2023 at 12:43:27PM +0100, Sergio Carlavilla wrote= : >>> On Mon, 30 Jan 2023 at 12:31, Mathieu Arnold wrote: >>>=20 >>=20 >>> This feels like a regression, docbook allowed us to mark things up >>> semantically, >>=20 >> Yes, but this is in Docbook, not in AsciiDoc. >>=20 >> For AsciiDoc the syntax [.whatever]## is to declare a class for the CSS p= arser. >> The result in the HTML, PDF and EPUB will be the same. >> Using [.whatever]## or ``. >>=20 >> But of course, this is my personal opinion, if you think is better to >> use the old syntax, please send an email to doceng@ >> Of course, this kind of changes must be decided by the entire Doceng@ >> not only a member of them. >=20 > This is exactly my point, if you write `foo`, you cannot affect the > rendering so that variable `foo` is different than filename `foo` or > code block `foo`, which is why we should keep [.filename]#foo#, and if > it was ever a thing, [.variable]#foo#, so that rendering can be made > different, and people reading the documentation have a better > experience, like, if something is in fixed width font, and in green, > (which was the color when we used docbook, I think,) then I know it's a > filename, I don't have to figure it out by using context. I agree that the semantics are useful and, arguably, should not have been dr= opped without discussion with doceng@ (or in earlier times, doc@) in the fir= st place. I=E2=80=99d hope that discussion could cover whether it is more i= mportant that people can contribute =E2=80=9Ceasily=E2=80=9D (and how one wo= uld measure if that is working) or a richer documentation set that can easil= y provide contextual output in various formats (and which ones are actually g= etting asked for or used). However, that all leads me back to my usual moan about engineering goals and= I wasn=E2=80=99t here and I haven=E2=80=99t succeeded in getting this acros= s before, so I=E2=80=99ll leave my opinion there. Ceri