Proposal: Include css for docs in emacs repo

Proposal: Include css for docs in emacs repo

[Daniel Radetsky]

I would like to build the emacs manuals for local use. This
means the one-page-per-node manuals. Ideally, I'd like to
build them with one command, and generate a self-contained
directory I could chuck somewhere (e.g. under my designated
serve-docs-from-local dir) and be able to browse them just
like I can on the gnu site.

Even if the docs build itself didn't currently leave
something to be desired, the built docs will contain the
following

<style type="text/css">
@import url('/software/emacs/manual.css');
</style>

Which refers to css not included in the repo itself. I'm not
sure if it's included in any repo. Personally, I just
downloaded the file (and the style.css file it referenced)
off of gnu.org. It would be nice if instead, these 2 files
were placed in a manual-assets/ dir alongside emacs/ elisp/
and friends, and if the manuals were to reference the
manual.css file contained in this dir with a relative path,
rather than the one at /software/emacs/manual.css.

There's no reason why gnu.org couldn't override this file
somehow, such that e.g. all manuals served from gnu.org
would continue to use /software/emacs/style.css instead of
the relative one, although I can't see why you'd want to.
But you could.

Anyway, I could concievably hack on the manual-generating
scripts myself (especially if the release-process docs were
a little clearer), but it won't actually accomplish my
purpose if we haven't moved the css to the emacs repo.

Re: Proposal: Include css for docs in emacs repo

[Eli Zaretskii]

> Date: Mon, 2 Dec 2024 19:32:39 -0800
> From: Daniel Radetsky <dradetsky@gmail.com>
> 
> I would like to build the emacs manuals for local use. This
> means the one-page-per-node manuals. Ideally, I'd like to
> build them with one command, and generate a self-contained
> directory I could chuck somewhere (e.g. under my designated
> serve-docs-from-local dir) and be able to browse them just
> like I can on the gnu site.
> 
> Even if the docs build itself didn't currently leave
> something to be desired, the built docs will contain the
> following
> 
> <style type="text/css">
> @import url('/software/emacs/manual.css');
> </style>

How do you get this?  Is that by running the scripts in the admin/
directory, like make-manuals?  Those scripts are for generating
manuals we upload to the GNU Software Documentation site, they are not
for users to generate HTML docs.  For the latter purpose, you are
supposed to say

  $ cd doc/emacs && make emacs.html HTML_OPTS='--html --split=node'

> Which refers to css not included in the repo itself. I'm not
> sure if it's included in any repo.

It is part of the Emacs "webpages" repository, which you can browse
here:

  http://web.cvs.savannah.gnu.org/viewvc/emacs/emacs/

> Personally, I just
> downloaded the file (and the style.css file it referenced)
> off of gnu.org. It would be nice if instead, these 2 files
> were placed in a manual-assets/ dir alongside emacs/ elisp/
> and friends, and if the manuals were to reference the
> manual.css file contained in this dir with a relative path,
> rather than the one at /software/emacs/manual.css.

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.

> Anyway, I could concievably hack on the manual-generating
> scripts myself (especially if the release-process docs were
> a little clearer), but it won't actually accomplish my
> purpose if we haven't moved the css to the emacs repo.

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.

Re: Proposal: Include css for docs in emacs repo

[Daniel Radetsky]

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.

> 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. 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.
Otherwise, I'll end up doing some kind of
works-on-my-machine hack to get the css into my local build,
and then the docs go up for regular users and look
incorrect.

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

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?

--dmr

Re: Proposal: Include css for docs in emacs repo

[Eli Zaretskii]

> Date: Tue, 3 Dec 2024 16:25:28 -0800
> From: Daniel Radetsky <dradetsky@gmail.com>
> 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.

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.

Re: Proposal: Include css for docs in emacs repo

[Eli Zaretskii]

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