Re: Proposal: Include css for docs in emacs repo

[Daniel Radetsky]

On Wed, Dec 04, 2024 at 02:51:59PM +0200, Eli Zaretskii wrote:
> Sorry.

Well, I'm not _happy_, but it does make sense to me. Sort of.

I'm going to go into a little more detail and just
double-check that you object to the actual proposal, not
some hypothetical even-dumber-than-my-usual-suggestions
version, and also say a few other things.

> 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.

Looking back and attempting to reconstruct my thought
process, I _think_ it's the fact that --split=node is not
referenced in the root makefile, but e.g. dvi/pdf/ps is.
Because I'm not the best at make, I didn't see

$(DOCS):
        $(MAKE) -C doc/$(subst -, ,$@)

and immediately think "of course I know what that means" so
rather than jumping straight to doc/emacs/Makefile, I just
did a repo search for stuff related to html-per-node and
quickly hit /admin and assumed that was just the one and
only way those manuals were generated. The fact that the
code used by admin was so convoluted similarly prevented me
from quickly seeing that it was just calling out to the way
users were supposed to do things^1.

So overall, while it might be slightly more intuitive if the
rule was written

$(DOCS):
        $(MAKE) --directory doc/$(subst -, ,$@)

I think we can chalk this one up to me not being smart.
Oops.

> > 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.

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.

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.

> > 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

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');

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.

I say "some prefix of" because not all of those 3 are
strictly required, just that the more that can be included
in the repo, the happier I would be.

Thus when you say

> 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

it's understandable if this is still your position, but I'm
not asking that a whole lot of content be kept in good
order. Also it's not just for my local use (although
admittedly that was the impetus); there are other
applications as well.

> 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.

To belabor the point, there is no question of cross-linking
any repositories^2. We could just download style.css to /tmp
(like, with wget -O) and then copy it to each output dir.

--dmr

[^1]: I mean, assuming that's what it is in fact doing; I
still haven't been able to see where that happens.

[^2]: I understood "cross-linking" to mean "something
git-submodule-flavored". Obviously this involves using
content from one repo in another.