Re: Proposal: Include css for docs in emacs repo

[Eli Zaretskii <eliz@gnu.org>]

> Date: Tue, 10 Dec 2024 11:05:05 -0800
> From: Daniel Radetsky <dradetsky@gmail.com>
> 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.
> 
> <style type="text/css">
> @import url('./manual.css');
> </style>
> 
> 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.