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: Sat, 14 Dec 2024 12:09:40 +0200 Message-ID: <86o71evamz.fsf@gnu.org> References: <86a5dc3ont.fsf@gnu.org> <868qsv1uhc.fsf@gnu.org> Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="25014"; 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 Sat Dec 14 11:10:00 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 1tMP5z-0006M1-N9 for ged-emacs-devel@m.gmane-mx.org; Sat, 14 Dec 2024 11:09:59 +0100 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tMP5l-0007pn-Mx; Sat, 14 Dec 2024 05:09:45 -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 1tMP5l-0007pb-07 for emacs-devel@gnu.org; Sat, 14 Dec 2024 05:09:45 -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 1tMP5k-0002DM-OL; Sat, 14 Dec 2024 05:09:44 -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=Awrorz/N++939VCU161VRSn6tA26Es+bF7SlTj0E4dM=; b=JokorN9DD3zz qLlgSWY6dKPm1R2GGIFwEXoG9dMFEBABKuqsTDJwg9xSlAgkQBMbhUjLKWu3EqcGGtIgyt3NH7wVC OzizfB8UQs0+ocCllVAwrq+6hMykTLlgzMqCGePEU844uTiX72AC1P32YiBiiefeHaofu2JkYSHUc lzh8QCQfUzZZwHo7yHNeHueQv4eCgwegnDfdSDPDxosQP+wZ2jZFjODGfUau6SoT2J0I9ZdjVUYwY 3WSl/O0Hbze3VlAVzjyCla1PRH0ipLQpRqsMExwCkUaZ9urg5Kz5FdXvUU4YJy58RowP2QGvfT6MQ mvyfx7iLAJ6vlgfFVfccog==; In-Reply-To: (message from Daniel Radetsky on Tue, 10 Dec 2024 11:05:05 -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:326474 Archived-At: > Date: Tue, 10 Dec 2024 11:05:05 -0800 > From: Daniel Radetsky > Cc: emacs-devel@gnu.org > > > > 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. > > It's a minor point, but I referred to someone _working on > the docs_ advisedly. As in, I'm writing docs for some part > of emacs and those docs should, among other things, look > correct when viewed on gnu.org. Therefore, I want to produce > them as they appear on gnu.org, especially if I'm doing > something slightly weird. There's no such requirement for contributors to the Emacs manuals. Those contributors need only to make sure the manuals produced by the Makefiles in the Emacs's doc directory look well. The rest is the job of the Emacs maintainers who produce the versions of the manuals to be uploaded to the GNU Documentation site. If the manuals don't look well on that site, people will report bugs, and we will need to fix those bugs and re-upload the fixed manuals. > I mean, it's fair to say that it's the responsibility of > gnu.org to not break otherwise-fine html docs with whatever > css it adds for its own look/feel purposes, but nobody said > this explicitly so I wasn't sure. See above. This is not the responsibility of people who submit changes for our manuals. > I guess it's that the gnu.org use-case is kinda weird to me. > Like I usually make projects where if a project output is > wrong, that's considered an issue in that repo which should > ideally not make it out of the repo. So if one of the > outputs of the repo is docs for gnu.org, I should be > building/inspecting my work in docs-for-gnu.org form, and if > I'm not doing this I'm being a bad dev. As I explained, this is more complicated in our case. There are two separate repositories involved, and the flow between them is unidirectional: from Emacs to the webpages, not the other way around. > > > 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 > > I think you may be misunderstanding what a small ask this > is, so I want to double-check you're saying no to what I'd > actually need in this case, which is some prefix of: > > 0. The ability to add e.g. > > > > to the generated docs This is done by the scripts that edit the HTML manuals into the form that the GNU Documentation site expects. > 1. To include a version of gnu.org/software/emacs/manual.css > (which contains 3 lines of css) in the repo, but with > > @import url('/style.css'); > > replaced with > > @import url('./style.css'); These CSS files are not developed by us, they are developed by the folks who maintain the GNU Documentation site. We don't want to be responsible for those files and we don't want them to be in our Git repository because they are already maintained in separate repositories. > 2. To add an option when building the docs which is false by > defaut and which, if true, causes the build to download > style.css from somewhere (probably the webpages repo) and > stick it the generated emacs.html/elisp.html/whatever dir. Sorry, I don't see the justification for this complication of the Emacs build procedures.