From nobody Tue Jan 31 09:07:54 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 4P5fN64Tqvz3btn8 for ; Tue, 31 Jan 2023 09:08:06 +0000 (UTC) (envelope-from carlavilla@freebsd.org) Received: from smtp.freebsd.org (smtp.freebsd.org [96.47.72.83]) (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 4P5fN6429rz479B; Tue, 31 Jan 2023 09:08:06 +0000 (UTC) (envelope-from carlavilla@freebsd.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1675156086; 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=howqOpie8ry6Ui79vA1MzrYglyhWhX36Mn6xLuE1TcU=; b=KqL7cLNfilgvv5fZ7HtNnSz+EGs3nk4IGBBNNXlCW9A/PeyEpRHG8b/Kk4oOI7LGnHGS6l fQbY69IN7WtcUDQx7xXLR9upIICZw63oVbX3iUXE1nkIORt0rsBqpmjWlnW8H25DRYpBRV 81WFBZhzkb0SCcF/bLRrOh//3s8TigY2Lz5gSAzWohF3wjDd80A3kW9zlideSObeS0sgZ1 fHAEk3LqNk8bv+tmDJYXH9aMa/Ak3ZYLxwuDacNj/VBx3w0xKVW9qVZxswcLtN8NiZ7xm9 bhkW+aBjMTYDI+4VqvqqKCkTOQFKfPXxonvOSG2a328kUMt9xaeIBHhJKHOxyg== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1675156086; 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=howqOpie8ry6Ui79vA1MzrYglyhWhX36Mn6xLuE1TcU=; b=bDU7moaI2WMK4vW18UaSxQodxOtMxrAQJ2jO1kZVMpSOOCOKhRCh5cdPf+dfXfJ/izdnlo TamvbFE2IRPS0WhKnCekp+q63QOxd2VEAJ3wr1cL/02/htmiVyqGbvLOXM3js6WlV2xYDJ aOu/ITKRqpuXGnrDGOGkQWS7fANBzwZxh/oNZfxTfx4Ryv+IUn+Kf2aGy7kSTc3ZK5Qjua ecQ3GjbfAas/e+ntVCly+yu0a0IlpXflrCJYCU38mVl3e2KFxvLkLbFf6CAcjdj8iUAq16 vQjjmSCbahQLEug9WcmLBW9LHolFhMXm1b2Gqm1wOzQqEUktKdv0c2d30u+lug== ARC-Authentication-Results: i=1; mx1.freebsd.org; none ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1675156086; a=rsa-sha256; cv=none; b=ZXVtKCAdKIQNGElj3r/GoO9vgKr0r3VvWnMvv2jV3iUzbPfCQlN+1ebkbHwVi4TyKP2PoL oNHhMvRfFhb0mm0ADhcTLNdwwyG89fFNiZl2YO7cKXOiQhStswyq6LHS9zbkWrqaZyHvVB 4Lty/98Jz5RB/FriPtqkwu0xijwHdjAWRQ/RW8R4CsIPO04pQWu+HbStmhs3zNE1CaUhWT hIfCoH+ouivhSyRETgQwz5rEP69bAiH5JaFotoBgqTzBAvNS3fkBPvG9fvgfl6NrZxIsjc u/het3o44hYglv/dtDl5bdVckuSP3w0ZGixJIETTci0MATYy1RCIEyO+NytDOA== Received: from mail-oi1-f169.google.com (mail-oi1-f169.google.com [209.85.167.169]) (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 4P5fN62m1xzW6S; Tue, 31 Jan 2023 09:08:06 +0000 (UTC) (envelope-from carlavilla@freebsd.org) Received: by mail-oi1-f169.google.com with SMTP id d188so12276020oia.3; Tue, 31 Jan 2023 01:08:06 -0800 (PST) X-Gm-Message-State: AFqh2kqZM8bBCu3MB2q8Pjvk9dZVuC98krGzxHltXCuP1pYVrj2R+sZa Gdp2CEvcXHIn6Gat/OfuenQ0//KddaGBGHzm8vc= X-Google-Smtp-Source: AMrXdXv/GuumNIRfvYCLFOU03tiTQ1J0emyQLFcA2lXvtDYm1YZFooaoGvv8MEnSPXOL06UB7+IYK8gV14mEttwC6wU= X-Received: by 2002:a54:4e8a:0:b0:363:f1fb:f580 with SMTP id c10-20020a544e8a000000b00363f1fbf580mr3251006oiy.201.1675156085682; Tue, 31 Jan 2023 01:08:05 -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> <20230131080243.zsxwgvx6qxfjjdc3@aching.in.mat.cc> In-Reply-To: From: Sergio Carlavilla Date: Tue, 31 Jan 2023 10:07:54 +0100 X-Gmail-Original-Message-ID: Message-ID: Subject: Re: To be deprecated [.filename]## tag in the document? To: ykla Cc: Mathieu Arnold , doceng@freebsd.org, "freebsd-doc@FreeBSD.org" Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable X-ThisMailContainsUnwantedMimeParts: N On Tue, 31 Jan 2023 at 10:02, Sergio Carlavilla wr= ote: > > On Tue, 31 Jan 2023 at 09:47, ykla wrote: > > > > So why not just use markdown, which is simpler and easier for more peop= le to learn? Just like vuepress https://handbook.bsdcn.org/ . > > > > Mathieu Arnold =E4=BA=8E2023=E5=B9=B41=E6=9C=8831=E6= =97=A5=E5=91=A8=E4=BA=8C 16:02=E5=86=99=E9=81=93=EF=BC=9A > >> > >> 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=C3= =B3: > >> > > > > >> > > > > Hi, > >> > > > > > >> > > > > I see that in some sections the [.filename]# # tags have been = replaced > >> > > > > with ` `, which does not effectively distinguish between folde= rs, device > >> > > > > symbols and specific commands, etc. > >> > > > > > >> > > > > Are there any plans for FreeBSD to do this across the board i= n the > >> > > > > future? I.e., do we need to do away with the [.filename]# # ta= g? > >> > > > > > >> > > > > 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, t= hey > >> > > used to be rendered as fixed with, in some color, so that they cou= ld be > >> > > differentiated from other fixed width stuff. > >> > > If I see `PKG` I just see something that will be rendered with a f= ixed > >> > > 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 parser. > >> > 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 othe= r option. > >> > 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 t= o > >> > 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. > >> > >> -- > >> Mathieu Arnold > > Hi, > > There's no *one* MD, there're a lot of flavours. Not only one.So you > cannot "learn'' one MD, you need to learn a lot of them.Also, AsciiDoc > has some functionalities that MD doesn't have, like callouts, > admonitions, etc. > > And the good point of AsciiDoc is there's only one AsciiDoc. You only > need to learn a single one. And as I said, have some functionalities > from the beginning without extensions, like callouts, etc. Apart from > the possibility to build custom functions, like the package, man, git > we're using right now. > > Bye! I forgot to say two things: In the first place, I'm gonna discuss with other Doceng members about the [filename] thing Secondly, I don't want to create a bikeshed about MD vs AsciiDoc. Bye!