* [PATCH] Documentation/technical/api-hashmap: Remove source highlighting
@ 2014-05-17 11:08 Anders Kaseorg
2014-05-17 15:22 ` Jeremiah Mahler
0 siblings, 1 reply; 6+ messages in thread
From: Anders Kaseorg @ 2014-05-17 11:08 UTC (permalink / raw)
To: Junio C Hamano; +Cc: git, Jonathan Nieder, 745591
The highlighting was pretty, but unfortunately, the failure mode when
source-highlight is not installed was that the entire code block
disappears. See https://bugs.debian.org/745591,
https://bugs.launchpad.net/bugs/1316810.
Signed-off-by: Anders Kaseorg <andersk@mit.edu>
---
Documentation/technical/api-hashmap.txt | 1 -
1 file changed, 1 deletion(-)
diff --git a/Documentation/technical/api-hashmap.txt b/Documentation/technical/api-hashmap.txt
index 42ca234..b977ae8 100644
--- a/Documentation/technical/api-hashmap.txt
+++ b/Documentation/technical/api-hashmap.txt
@@ -166,7 +166,6 @@ Usage example
-------------
Here's a simple usage example that maps long keys to double values.
-[source,c]
------------
struct hashmap map;
--
2.0.0.rc3
^ permalink raw reply related [flat|nested] 6+ messages in thread
* Re: [PATCH] Documentation/technical/api-hashmap: Remove source highlighting
2014-05-17 11:08 [PATCH] Documentation/technical/api-hashmap: Remove source highlighting Anders Kaseorg
@ 2014-05-17 15:22 ` Jeremiah Mahler
2014-05-18 0:50 ` Anders Kaseorg
0 siblings, 1 reply; 6+ messages in thread
From: Jeremiah Mahler @ 2014-05-17 15:22 UTC (permalink / raw)
To: Anders Kaseorg; +Cc: git
On Sat, May 17, 2014 at 07:08:55AM -0400, Anders Kaseorg wrote:
> The highlighting was pretty, but unfortunately, the failure mode when
> source-highlight is not installed was that the entire code block
> disappears. See https://bugs.debian.org/745591,
> https://bugs.launchpad.net/bugs/1316810.
>
I agree that a broken document is an unacceptable failure mode.
But I do not understand why 'source-highlight' is not an install
requirement for 'git-doc'. If I install 'source-highlight' on
my Debian machine the code looks great.
apt-get install source-highlight
I also noticed that this seems to be the single place where source
code highlighting is used in Documentation/technical.
So it might be worthwhile to eliminate this dependency all together
as Anders patch does.
--
Jeremiah Mahler
jmmahler@gmail.com
http://github.com/jmahler
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH] Documentation/technical/api-hashmap: Remove source highlighting
2014-05-17 15:22 ` Jeremiah Mahler
@ 2014-05-18 0:50 ` Anders Kaseorg
2014-05-19 17:09 ` Junio C Hamano
0 siblings, 1 reply; 6+ messages in thread
From: Anders Kaseorg @ 2014-05-18 0:50 UTC (permalink / raw)
To: Jeremiah Mahler; +Cc: git
On Sat, 17 May 2014, Jeremiah Mahler wrote:
> I agree that a broken document is an unacceptable failure mode.
>
> But I do not understand why 'source-highlight' is not an install
> requirement for 'git-doc'. If I install 'source-highlight' on
> my Debian machine the code looks great.
>
> apt-get install source-highlight
Yes; when I noticed this failure, I asked Jonathan to add source-highlight
as a build dependency in Debian (https://bugs.debian.org/745591). But
then Ubuntu forked the packaging to revert this change
(https://bugs.launchpad.net/bugs/1316810), because source-highlight in the
community-supported universe repository is not allowed to be a build
dependency of git in the Canonical-supported main repository. So now the
Ubuntu package still has broken documentation _and_ it’s lost the ability
to automatically synchronize updates from Debian.
If we’re going to make Git depend on source-highlight, then we would want
to make sure it’s documented in INSTALL and that its absence is properly
diagnosed. Maybe then we could make the argument to Canonical that
source-highlight should become officially supported in main
(https://wiki.ubuntu.com/UbuntuMainInclusionRequirements).
But I don’t that would be worth it just to make one page of the API
documentation a little more colorful (and it sounds like you agree).
Anders
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH] Documentation/technical/api-hashmap: Remove source highlighting
2014-05-18 0:50 ` Anders Kaseorg
@ 2014-05-19 17:09 ` Junio C Hamano
2014-05-19 23:40 ` Anders Kaseorg
0 siblings, 1 reply; 6+ messages in thread
From: Junio C Hamano @ 2014-05-19 17:09 UTC (permalink / raw)
To: Anders Kaseorg; +Cc: Jeremiah Mahler, git
Anders Kaseorg <andersk@MIT.EDU> writes:
> Yes; when I noticed this failure, I asked Jonathan to add source-highlight
> as a build dependency in Debian (https://bugs.debian.org/745591). But
> then Ubuntu forked the packaging to revert this change
> (https://bugs.launchpad.net/bugs/1316810), because source-highlight in the
> community-supported universe repository is not allowed to be a build
> dependency ...
The reasoning and solution Ubuntu has sounds sensible *but* it also
soudns like it is incomplete. If Ubuntu does not want to use
highlight, it can apply a change like the patch in question as part
of their fork to make the end result consistent and they are failing
to do so. If the tooling do not use highlight, the source should
not require highlight, either. It is ultimately their bug.
It however *is* our business, as their upstream, to make it easier
for distros that want to use and distros that do not want to depend
on highlight, and aiming for a solution that relieves Ubuntu or any
other distros from needing to carry one more patch is a good thing.
How bad does the documentation look with the patch applied (I know
how bad it looks without source-highlight installed)? If it is not
too bad, then it sounds like a sensible solution to drop the
highlight markup unconditionally like the patch that started this
thread does, taking the "common denominator" approach. You seem to
agree, and I do not object, either.
> But I don’t that would be worth it just to make one page of the API
> documentation a little more colorful (and it sounds like you agree).
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH] Documentation/technical/api-hashmap: Remove source highlighting
2014-05-19 17:09 ` Junio C Hamano
@ 2014-05-19 23:40 ` Anders Kaseorg
2014-05-20 17:31 ` Junio C Hamano
0 siblings, 1 reply; 6+ messages in thread
From: Anders Kaseorg @ 2014-05-19 23:40 UTC (permalink / raw)
To: Junio C Hamano; +Cc: Jeremiah Mahler, git
On Mon, 19 May 2014, Junio C Hamano wrote:
> If Ubuntu does not want to use highlight, it can apply a change like the
> patch in question as part of their fork to make the end result
> consistent and they are failing to do so.
Sure, Ubuntu can apply that patch, but the larger problem remains: if the
Ubuntu packaging is even slightly different from Debian’s, it is no longer
eligible for automatic synchronization from Debian.
When that has happened in the past, the result was that the Ubuntu version
languished far behind the Debian version, because Canonical doesn’t have
the manpower to manually merge every Debian update. Ubuntu 9.04 shipped
with Git 1.6.0.4 instead of 1.6.2.4 because they had failed to update
their packaging after patching out a dependency on cvsps.
If this Ubuntu nonsense were obstructing something important upstream,
then of course I would be yelling at Ubuntu to get their act together; in
that case, I filed a main inclusion report to get Canonical to officially
support cvsps (https://bugs.launchpad.net/bugs/369111) so Ubuntu could
drop their patch. But here we’re talking about syntax highlighting in one
page of internal documentation that basically nobody is going to read, and
that argument wouldn’t carry any weight.
We could put the patch into Debian instead of Ubuntu to eliminate the
Ubuntu delta; Jonathan has been friendly enough to Ubuntu that I think he
would grudgingly agree. But I’m submitting it upstream because other
distros will eventually run into the same problem: there’s no obvious cue
that source-highlight needs to be added as a new dependency besides a
warning message buried in the middle of the build log.
> How bad does the documentation look with the patch applied (I know how
> bad it looks without source-highlight installed)? If it is not too bad,
> then it sounds like a sensible solution to drop the highlight markup
> unconditionally like the patch that started this thread does, taking the
> "common denominator" approach. You seem to agree, and I do not object,
> either.
Original version with syntax-highlight installed (pretty):
http://web.mit.edu/andersk/Public/api-hashmap/old-highlight.html
Original version with syntax-highlight missing (corrupted):
http://web.mit.edu/andersk/Public/api-hashmap/old-no-highlight.html
Patched version (boring but readable):
http://web.mit.edu/andersk/Public/api-hashmap/patched.html
Anders
^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2014-05-20 17:31 UTC | newest]
Thread overview: 6+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2014-05-17 11:08 [PATCH] Documentation/technical/api-hashmap: Remove source highlighting Anders Kaseorg
2014-05-17 15:22 ` Jeremiah Mahler
2014-05-18 0:50 ` Anders Kaseorg
2014-05-19 17:09 ` Junio C Hamano
2014-05-19 23:40 ` Anders Kaseorg
2014-05-20 17:31 ` Junio C Hamano
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.