Re: [Docutils-users] source-url should not imply source-link

[Beni C. <cb...@us...>]

David Goodger wrote on 2003-12-15:

> [Still catching up on email...]
>
> Beni Cherniavsky wrote:
>  > When doing any preprocessing on docutils, it's useful to give the
>  > real source file name with --source-url.  It makes sense to give the
>  > option e.g. in a makefile.
>
> I don't understand the motivation.  --source-link and --source-url are
> used only to produce a source link in the output's footer.  They're
> not used anywhere else in Docutils' code.  --source-link calculates a
> relative URL based on the source file's path.  --source-url is simply
> a variation which is used when an explicit URL is desired, potentially
> unrelated to where the source file is at process time.
>
Indeed, you can look at it so: both set the source URL to a known
value.  What I want then is to have a (third?) option to control
whether the URL is displayed in the footer or not.

>  > The problem is that doing so forces the source link to be displayed,
>  > which is matter of taste and should be controlled from the config
>  > file.  Currently, I need to give --source-url in the makefile if I
>  > want it shown and omit it if I don't.  I propose to remove this
>  > option coupling, so that one can always give the option and leave
>  > control whether to show it or not to the source-link option.
>
> The change is backward-incompatible.  After the proposed change,
> anybody who currently uses --source-url would have to add a
> --source-link option (or config setting), potentially breaking
> toolchains.

True.  My proposal was a quick idea.  A backward-compatibile solution
would be better.

> I think it's useful for --source-url to imply --source-link; saves a
> step.  You're asking for a change that makes your setup simpler, but
> everyone else's more complex.
>
You have a point.

> If it's easier to switch on inluding/excluding the link in your
> Makefile, how about including a --no-source-link option when you
> *don't* want a link?
>
> I think I see what you're after though.  You want to be able to
> specify the URL on the command line, but control the link's display
> (on or off) in the config file.  But in Docutils' model, command-line
> options have priority over config file settings (we've covered this
> ground before).

That's precisely why a ``--no-source-link`` option on the command
line won't solve my problem.

> Perhaps rather than changing the definition of
> --source-url to not imply --source-link, we could do the following:
>
> * Make --source-link still imply --source-url, but set
>    settings.source_url independently of settings.source_link.
>
> * Make --no-source-link unset settings.source_link only; leave
>    settings.source_url alone.
>
> * In your Makefile, specify "--source-url <URL> --source-link --config
>    <extra_conf>".  The extra_conf file can have "source-link = on" or
>    "= off".
>
The last part is a dirty way to work around IMHO.  Ideally a single
config file should be able to set up all things.  I think some new
option is needed (if backward compatibility is important).

I think the best way would be to add a variant of ``--source-url``
(can't think of a good name, only ``--source-url-hint`` but that's
unobvious) that won't change `source_link`.  The benefit of a new
option is that you don't lose the convenient step-saving behavior.

> Or am I putting too much weight in backwards-compatibility?  Opinions
> welcome.
>
I don't object ot breaking it but I obviously I can't speak for
others.

> For reference, here's Beni's patch:
>
> Index: docutils/transforms/universal.py
> ===================================================================
> RCS file: /cvsroot/docutils/docutils/docutils/transforms/universal.py,v
> retrieving revision 1.19
> diff -u -r1.19 universal.py
> --- docutils/transforms/universal.py    10 Apr 2003 16:03:45 -0000      1.19
> +++ docutils/transforms/universal.py    17 Nov 2003 21:26:41 -0000
> @@ -53,11 +53,10 @@
>           # @@@ Text is hard-coded for now.
>           # Should be made dynamic (language-dependent).
>           settings = self.document.settings
> -        if settings.generator or settings.datestamp or
> settings.source_link \
> -               or settings.source_url:
> +        if settings.generator or settings.datestamp or
> settings.source_link:
>               text = []
> -            if settings.source_link and settings._source \
> -                   or settings.source_url:
> +            if settings.source_link \
> +                   and (settings._source or settings.source_url):
>                   if settings.source_url:
>                       source = settings.source_url
>                   else:
>
>

-- 
Beni Cherniavsky <cb...@us...>
Note: I can only read email on week-ends...

But the delight and pride of Aule was in the process of making, and in
the thing made, and not in possesion nor in himself, wherefore he was
a maker and teacher and not a master, and none have called him Lord.
-- J.R.R.Tolkien, Ainulidale, The Lost Road and Other Writings, p. 175