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