From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.devel Subject: Re: Proposal: Include css for docs in emacs repo Date: Wed, 04 Dec 2024 14:51:59 +0200 Message-ID: <868qsv1uhc.fsf@gnu.org> References: <86a5dc3ont.fsf@gnu.org> Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="32122"; mail-complaints-to="usenet@ciao.gmane.io" Cc: emacs-devel@gnu.org To: Daniel Radetsky Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Wed Dec 04 13:53:01 2024 Return-path: Envelope-to: ged-emacs-devel@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1tIosH-0008B1-H6 for ged-emacs-devel@m.gmane-mx.org; Wed, 04 Dec 2024 13:53:01 +0100 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tIorN-0004vR-S4; Wed, 04 Dec 2024 07:52:05 -0500 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1tIorK-0004v7-KM for emacs-devel@gnu.org; Wed, 04 Dec 2024 07:52:02 -0500 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1tIorK-00015U-Bl; Wed, 04 Dec 2024 07:52:02 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=References:Subject:In-Reply-To:To:From:Date: mime-version; bh=59pOI1aHCNnxLaJg8AqVRdyT8dZCzLi7c9LKQb+VmIU=; b=WVsnNhJDPaGz UnNJewF4p6K9dOQajneZ0swSilG1W0MgdGV2szx5+Axn/xZFI7ic5z1DU1sboj5wtzFYCwNVSsx8w ka+ymRs+PH6jf6nPzzT+ittBFdVFG/g6+2bX7uM8mgD7JM7/Prtj62rJPaVfiTqmyVCtBXpdt3LBs CpQWhQBIyf5/5OZnHMzPWaAeH3JL9ozUmUx4a2yag073SgNiRfOq/UIQtf3DammNUD3qS59DOKxjw 9qwD6ycIzFW5tzUg1akZYXclmObVYbQF4ESReaifeCi4RFQvdmK4gfwdsTIvmbIovq788iig2vLC8 7kvCKjj3SE0Wvp8m8e8bhQ==; In-Reply-To: (message from Daniel Radetsky on Tue, 3 Dec 2024 16:25:28 -0800) X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Xref: news.gmane.io gmane.emacs.devel:326025 Archived-At: > Date: Tue, 3 Dec 2024 16:25:28 -0800 > From: Daniel Radetsky > Cc: emacs-devel@gnu.org > > On Tue, Dec 03, 2024 at 03:02:30PM +0200, Eli Zaretskii wrote: > > How do you get this? Is that by running the scripts in the admin/ > > directory, like make-manuals? > > Yes, that's what I did. > > > For the latter purpose, you are supposed to say > > > > $ cd doc/emacs && make emacs.html HTML_OPTS='--html --split=node' > > Thanks, although I didn't realize that. I spent some time > looking around for how to do it, but didn't figure it out. > Does that mean I'm not very smart, or that the process is > not very intuitive, or some combination of both? Hard to > say. Which part(s) are missing? The makeinfo option to produce HTML split by node is documented in the Texinfo manual (where makeinfo is documented), and the rest you can find by looking at doc/emacs/Makefile in the source tree, like any other Make target that isn't run as part of the standard build. > > I don't see a need to include this in the Emacs Git repository. The > > stuff related to the Web documentation is maintained in a separate > > repository for a reason. > > I'm not sure I'd call it a "need" but the reason is that so > that as a user, I can build the html docs for personal use > without having to do weird stuff like manually downloading > the css from gnu.org. See above: users are not supposed to build the HTML versions of the manuals this way, and thus don't need to run these scripts or use that file. That's why the scripts are in the admin directory and not in the doc directory. You don't need that file unless you run the scripts in admin to produce the manuals in the form we upload them to the GNU Documentation site. > Also, as somebody who is working on > the docs, it's desirable to be able to build the docs > exactly as they would appear to a user on gnu.org. No, because the manuals produced for the GNU Documentation site have specific requirements which are not relevant to users who want to produce the HTML docs locally. The main reason for using that CSS file is to make sure the produced manuals match the general look-and-feel of the other GNU manuals on the GNU site, and fit well into the menu structure of that site. These requirements are not relevant to users, and IMO are a big PITA, but we must comply to them when we upload manuals to the GNU site. > > The way these scripts are used is described in admin/make-tarball.txt. > > You will see there that the produced HTML manuals are moved to the > > separate webpages repository and sent upstream from there; the file > > manual.css is part of that repository. So there's no need to mix this > > with the Emacs sources, because Emacs users are not supposed to > > produce manuals in the format used for the GNU Documentation web site. > > Sure, but some emacs users don't play by your rules, maaaaan > [takes a hit of joint]. That's fine, but you cannot expect the Emacs maintainers to bear the additional burden of what you want to do locally for your personal needs that are not supported by the project for users in general. I've told you where this file is stored, so you can in the future download it from that repository, and do whatever you want. > I suppose it would work to just download style.css from the > repo when I wanted to make a user-type (as opposed to > admin-type) html docs build. We could also include a custom > version of manual.css (but not style.css) for this use > intended to just point to a relative path. rather than an > absolute path. Would some version of this be acceptable? Sorry, no. Producing the manuals in the format for that site is an annoying job, it takes quite some time, produces several versions of the manuals, is prone to errors (in particular, the code in admin.el edits the resulting HTML, and might fail spectacularly if one happens to use a version of Texinfo not close enough to the one for which the scripts were prepared), and is quite tedious. I object to asking us to keep this stuff in good enough order for general user audience just because you want for some reason to use them for your local HTML manuals, something that is not what we recommend doing in those cases. The CSS file itself is not the problem, but it is the tip of a very large iceberg, in particular because the files are kept in a separate repository under a different VCS, and cross-linking these two repositories is not really a good idea, and neither is duplicating the file. Sorry.