[PATCH] Documentation/technical/api-hashmap: Remove source highlighting

[PATCH] Documentation/technical/api-hashmap: Remove source highlighting

[Anders Kaseorg]

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

Re: [PATCH] Documentation/technical/api-hashmap: Remove source highlighting

[Jeremiah Mahler]

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

Re: [PATCH] Documentation/technical/api-hashmap: Remove source highlighting

[Anders Kaseorg]

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

Re: [PATCH] Documentation/technical/api-hashmap: Remove source highlighting

[Junio C Hamano]

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

Re: [PATCH] Documentation/technical/api-hashmap: Remove source highlighting

[Anders Kaseorg]

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

Re: [PATCH] Documentation/technical/api-hashmap: Remove source highlighting

[Junio C Hamano]

Anders Kaseorg <andersk@MIT.EDU> writes:

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

Thanks.  I've queued the patch for v2.0 and the comparison between
the first and the third clearly shows that it is the right thing to
do ;-).