From nobody Mon Jan 30 11:43:27 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 4P55t34J9wz3cMTH for ; Mon, 30 Jan 2023 11:43:39 +0000 (UTC) (envelope-from carlavilla@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 4P55t33gqnz49q5; Mon, 30 Jan 2023 11:43:39 +0000 (UTC) (envelope-from carlavilla@freebsd.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1675079019; 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: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=ZkfOLlB2VLbY5fkvnY3vs1urE5o9JepR2d6K/MPvmi4=; b=gP4grYQGe9xRb+ADrh5KZz/buYoRWFMoC0SHQHy3s2fwkCaU2RRA0vwp61YCrjMMntjqNN m7QMKohUjOQH5Rds0PEe6agynSnPFLeTSjZWfY7tdkPq7jIy44cpZTBUCYMJ6Ylv7FLiUs saTbY7wSMaJP/TdsAy0zjaWoWCkIQnD7sYIZ2dXXXp4ixpXM/fettJsI/5E7stNdfdM4WT 6Uu0gUzsMcHlmtfmg56u4P6IkzWWrynLdx2JC5pNP7FNxdhrzJ2Gf02uGAZU5HEAV4/0cW UmLMRtZ6HMKM7Nqeo42oIcW9fShjrakdNYP+Hz+afqcxiRSvXE0TK2N9c9dLGA== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1675079019; 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: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=ZkfOLlB2VLbY5fkvnY3vs1urE5o9JepR2d6K/MPvmi4=; b=WDhpjw4d7guVdfVz8f+QdMeVk5cJyQEYBFBJVUjeFY/M1hMtLgYpTzMCOBZGHv+I/wMm0E +MFoo5U1c6eVbLtyvZzKK+RZP+7M531qthtk3252MKiBYOHOIMi+CnltcVrSJ0awaulHUh XQI+RZC+OBE27jGZRl7gHTYXcMJ7SPX+nD0MTLuNqwwJ2ktE12UdeDPb61tluYfD6slurw J2LlUsN8bN8TB7mHIYbTEUHRgL0hHS6nVPb7Xpepz0dBNC4g7FHEMd/hYRsm2iwXrBmGsI Cl8kquWTQWjzF/oQJyVHhaNDAJuGmsSUNLd2O+D5qLhDJL7impJwHhTySLILQA== ARC-Authentication-Results: i=1; mx1.freebsd.org; none ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1675079019; a=rsa-sha256; cv=none; b=Odcnf7ONi4et6Y2iQJVBKKL8gZRmy4Uo2mv7Aa/+Q7GskXIF7poSqgNnx1NX+TaT/XXHvB t0j4bLYXkwXVFK7Up9NaYlFlUCNjTl9Uuh0T4PY2Afy5lCnrPBfgRILO9o+VmKbde47SIR /Vyl8uX4HvGoXESaXMh4rmf5YDiCLBS+qnQhYS5FNLSEz90MroEtI6t9hw1bLQaRFu0dw9 lD3DlcgcKQ5KjkMbeD/fyHOV2hjzGfwJ/7qz35lfDxdF0Lh6qqy4dF5e46T+B8Tmv/RWjY tpYeR9Uwm5HsXYAfyb8WD2EUvXjmIwX+dOSbcq1OFR7hC+KxNi0+te8kdgYa3g== Received: from mail-oi1-f175.google.com (mail-oi1-f175.google.com [209.85.167.175]) (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)) (Authenticated sender: carlavilla) by smtp.freebsd.org (Postfix) with ESMTPSA id 4P55t32dw1z1Lbh; Mon, 30 Jan 2023 11:43:39 +0000 (UTC) (envelope-from carlavilla@freebsd.org) Received: by mail-oi1-f175.google.com with SMTP id r9so9769592oig.12; Mon, 30 Jan 2023 03:43:39 -0800 (PST) X-Gm-Message-State: AFqh2ko1GjzOH7Wn695POOaQMAIapyvitU3C94PXkDbmkYfKrDUBZ6NY Q1GDUwXxFRpe7g2W7D4NgaXzfw15DMM/vAZnKrQ= X-Google-Smtp-Source: AMrXdXvERxMZ6UHy1DndWpegEk3tsTL6T+6WuG0hZnkKHYYuvaMwCGp/36QubLjGfgVmTShfnrBNfOmzWGr1KxLeGiE= X-Received: by 2002:a54:4e8a:0:b0:363:f1fb:f580 with SMTP id c10-20020a544e8a000000b00363f1fbf580mr3009070oiy.201.1675079018759; Mon, 30 Jan 2023 03:43:38 -0800 (PST) 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 References: <20230130113056.rxdp4ajyh5adayl4@aching.in.mat.cc> In-Reply-To: <20230130113056.rxdp4ajyh5adayl4@aching.in.mat.cc> From: Sergio Carlavilla Date: Mon, 30 Jan 2023 12:43:27 +0100 X-Gmail-Original-Message-ID: Message-ID: Subject: Re: To be deprecated [.filename]## tag in the document? To: Mathieu Arnold Cc: ykla , "freebsd-doc@FreeBSD.org" Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable X-ThisMailContainsUnwantedMimeParts: N 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=C3=B3: > > > > > Hi, > > > > > > I see that in some sections the [.filename]# # tags have been replace= d > > > with ` `, which does not effectively distinguish between folders, dev= ice > > > 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 Hi, > This feels like a regression, docbook allowed us to mark things up > semantically, Yes, but this is in Docbook, not in AsciiDoc. For AsciiDoc the syntax [.whatever]## is to declare a class for the CSS par= ser. The result in the HTML, PDF and EPUB will be the same. Using [.whatever]## or ``. Personally, for me it is easier to read/write `` instead of the other optio= n. But not only in AsciiDoc, algo in Github MD, Gitlab MD, etc. 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. If you see some changes in the Handbook right now it is because as I said, it is easier to read/write the other option for me. Bye and hope this explanation works. Sorry for the shortness, I'm at my work at I cannot explain this better heh= e