From nobody Tue Jan 31 08:02:43 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 4P5cwk1zx6z3bV2v for ; Tue, 31 Jan 2023 08:02:46 +0000 (UTC) (envelope-from mat@freebsd.org) Received: from smtp.freebsd.org (smtp.freebsd.org [IPv6:2610:1c1:1:606c::24b:4]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "smtp.freebsd.org", Issuer "R3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4P5cwk1Sw6z42sW; Tue, 31 Jan 2023 08:02:46 +0000 (UTC) (envelope-from mat@freebsd.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1675152166; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: in-reply-to:in-reply-to:references:references; bh=q09NQNg3Xd+vutrXzCmDtBmlyjowHJxwYaboCc3EjpY=; b=aXohUxshF4C5SVyI6eJ1FKflvdBtlSGupH4DnjOEzDyr05W2mUO8+In+w/8GsVJOuAAisQ dr+SEQ7SuV8yBbdmRfHENwEyvxi6kTKHCZBcJtxhe4O10S7ueaFHtrXTDnLZmXH/K1AdIK pAdvrkQOxcgsPYH87WXW3N4JV9thARUi4ZNZAEhImz4wlCgx1QNL2QJXiIcfAhIJLZydnY MIVDVG5/XMjqIJ0VlcDSkeZKnZhtZZa8UzgEq3fisfBWMmHxk9q5hyE4CV63nj9frIN0TF f/z1sRe86XKi0ChvCn5xDlO1yuciyxSLWNhdlGpMdqdoLQqf+zPLIQLLmId71Q== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1675152166; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: in-reply-to:in-reply-to:references:references; bh=q09NQNg3Xd+vutrXzCmDtBmlyjowHJxwYaboCc3EjpY=; b=fKBSyysc3ad9rM8kPjJoc90WGuXRClVlJJ6jLNmWTGPwWWe52GRM+IjetqZiolEa5qvzSp HU3vr9l4CBlPm0Qp3aae7lvUdSgvMwFkGSpXcWEr5YDQJ7z9vGFPiFiS83hiMfrgeAIkZk FuspNn6LxXLFpF8CChi5TbIO+7BsOJPwOrPzEn/DDaqurAL6+5ZVXNwOsL+3izmx2dXWRG vekr27iyjp0T/nhVR4gkJqQCoR2S2VAznKxLIpTw+3cPMJsbE/L1+NVl8DKY4FIR0jCc4j uDkLVvqOj9io9aL4BxT2YXSy2/tFgz1czTfIZFc6/VmJnkt7lCWPrN+GbL9jEA== ARC-Authentication-Results: i=1; mx1.freebsd.org; none ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1675152166; a=rsa-sha256; cv=none; b=dyeeOLerHRCLAdFUzFKwlDc1le34I14r1bI/eKO2pg5y81QM1v5V4hl3VnXl7xYpHfUyo/ wcw7MsGr6ehPggEN5KTkO4TTXXgILCyDe1cSklblaWN9tx5MtHoTxqchj0pKdMcjztX8ZL iQja3RHzr1p/9Lgey2bAtNX1UE/No1dq0kdAlI4XcirK2FO3dNq8jRnzmc+qGhmzMajnbc IAv5c07adJu2/DAmRa9ZYQd6yvf2FziPIn5+fi/vU5SGsz4STO3CJj9tlUXeIGprukOSrm Ko0d88WkUA9OctLQH6ruNX/q1pWoEZDGwHVL/GxyYuDfodWkH7a9bB+KHh6rLQ== Received: from mail.j.mat.cc (owncloud.cube.mat.cc [79.143.240.228]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mail.mat.cc", Issuer "R3" (verified OK)) (Authenticated sender: mat/mail) by smtp.freebsd.org (Postfix) with ESMTPSA id 4P5cwj6z0CzVfV; Tue, 31 Jan 2023 08:02:45 +0000 (UTC) (envelope-from mat@freebsd.org) Received: from aching.in.mat.cc (unknown [IPv6:2a01:e0a:836:f670:5c75:e4da:5c24:bc03]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange ECDHE (P-256) server-signature RSA-PSS (4096 bits) server-digest SHA256) (No client certificate requested) (Authenticated sender: mat@mat.cc) by mail.j.mat.cc (Postfix) with ESMTPSA id A1239942D80; Tue, 31 Jan 2023 08:02:44 +0000 (UTC) Date: Tue, 31 Jan 2023 09:02:43 +0100 From: Mathieu Arnold To: Sergio Carlavilla , doceng@freebsd.org Cc: ykla , "freebsd-doc@FreeBSD.org" Subject: Re: To be deprecated [.filename]## tag in the document? Message-ID: <20230131080243.zsxwgvx6qxfjjdc3@aching.in.mat.cc> References: <20230130113056.rxdp4ajyh5adayl4@aching.in.mat.cc> 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 Content-Type: multipart/signed; micalg=pgp-sha512; protocol="application/pgp-signature"; boundary="2dftrqrd3isqa7yv" Content-Disposition: inline In-Reply-To: X-ThisMailContainsUnwantedMimeParts: N --2dftrqrd3isqa7yv Content-Type: text/plain; charset=iso-8859-1 Content-Disposition: inline Content-Transfer-Encoding: quoted-printable On Mon, Jan 30, 2023 at 12:43:27PM +0100, Sergio Carlavilla wrote: > On Mon, 30 Jan 2023 at 12:31, Mathieu Arnold wrote: > > > > On Mon, Jan 30, 2023 at 11:36:05AM +0100, Sergio Carlavilla wrote: > > > El jue., 26 ene. 2023 8:21, ykla escribi=F3: > > > > > > > Hi, > > > > > > > > I see that in some sections the [.filename]# # tags have been repla= ced > > > > with ` `, which does not effectively distinguish between folders, d= evice > > > > symbols and specific commands, etc. > > > > > > > > Are there any plans for FreeBSD to do this across the board in the > > > > future? I.e., do we need to do away with the [.filename]# # tag? > > > > > > > > ykla > > > > . > > > > > > > > > > Hi, > > > > > > Yes, the idea is to remove the [.filename]## tag and use `` > > > > > > This is from the migration of Docbook to AsciiDoc. > > > > But, why? > > > > This feels like a regression, docbook allowed us to mark things up > > semantically, like, we would know what was a variable, a filename, a > > code block... The idea was to be able to differentiate things, and let > > the rendering do the right thing. > > If I see [.filename]#PKG# I clearly see it refers to a filename, they > > used to be rendered as fixed with, in some color, so that they could be > > differentiated from other fixed width stuff. > > If I see `PKG` I just see something that will be rendered with a fixed > > with font, but I have no idea what it refers to. > > > > -- > > Mathieu Arnold >=20 > Hi, >=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 > Personally, for me it is easier to read/write `` instead of the other opt= ion. > But not only in AsciiDoc, algo in Github MD, Gitlab MD, etc. >=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. 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. --=20 Mathieu Arnold --2dftrqrd3isqa7yv Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- iQITBAABCgB9FiEE9XJBpJetWizkEBUef2IOCp6dQb4FAmPYyyNfFIAAAAAALgAo aXNzdWVyLWZwckBub3RhdGlvbnMub3BlbnBncC5maWZ0aGhvcnNlbWFuLm5ldEY1 NzI0MUE0OTdBRDVBMkNFNDEwMTUxRTdGNjIwRTBBOUU5RDQxQkUACgkQf2IOCp6d Qb45rwv/Y76j8QWD4kgXkVMf9bMBPup3zQ8HTI0ahnGvI6iQP1NAJOimET4bVLjT CZpzy7Q2q5gvmxhYJzo9gFsCxRYJctFmjrVlpmzKm06k1tfMbI1Mbs7iPavcx7lt QDhJpa1TzbaqssTOPAik2iXy4gSpswuz3j5NWL0JKftYpo0mmrKx/6oA4noQ3woB MkOiJ1FUq/qsC2DC26kGnXayLipGcM31KzNBrMRi7Cj6kTJv/UWsWx/GnWeTDSQt oVuxcFRzkJuD4rqz1Qp7FRa8HN8hnLuQWPfvRLYb9VsbMDXwu7Bf3EXPUcZ6JoJk d2RD7QsffxNKHZxU4PCvXB0ZtRt+UtYBDWHRsg70Jt5LRpeia/lqDWFYV7JUwxZb V5yKYS7HnvTU7v1P2KTQcT0p/fcjxmaYxD9QqC1W2F/sOAIufirTV15iWlNMTMyI MkzfSNsJek9LE6N65rlegw/8LVPqWkYYllOiNT1ahm2xIY3HwuoLdMcDUQ8uLEAj 9guIFUox =bOIy -----END PGP SIGNATURE----- --2dftrqrd3isqa7yv--