Removing core-spec.pdf from repository?

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
10 messages Options
Reply | Threaded
Open this post in threaded view
|

Removing core-spec.pdf from repository?

Ben Gamari-3
Hello everyone,

Currently there is a typeset copy of the Core specification in the GHC
repository. This means any time someone changes the specification the
repository grows by around 300kB. While this isn't the end of the
world, it's generally considered bad form to put generated files under
version control.

Of course, the tools required to typeset the specification (ott and
LaTeX) are non-trivial to install, so there is considerable convenience
that comes from having a typeset version readily available.

I suggest that we remove the PDF from the repository but instead I can
start including it in my nightly documentation builds. Any objections?

Cheers,

- Ben

_______________________________________________
ghc-devs mailing list
[hidden email]
http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs

signature.asc (497 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

RE: Removing core-spec.pdf from repository?

David Feuer-2
Kill it! That's terrible practice indeed. Speaking of generated files, it's time to check if our Unicode tables are up to date.



David Feuer
Well-Typed, LLP

-------- Original message --------
From: Ben Gamari <[hidden email]>
Date: 3/13/17 6:57 PM (GMT-05:00)
To: GHC developers <[hidden email]>
Subject: Removing core-spec.pdf from repository?

Hello everyone,

Currently there is a typeset copy of the Core specification in the GHC
repository. This means any time someone changes the specification the
repository grows by around 300kB. While this isn't the end of the
world, it's generally considered bad form to put generated files under
version control.

Of course, the tools required to typeset the specification (ott and
LaTeX) are non-trivial to install, so there is considerable convenience
that comes from having a typeset version readily available.

I suggest that we remove the PDF from the repository but instead I can
start including it in my nightly documentation builds. Any objections?

Cheers,

- Ben

_______________________________________________
ghc-devs mailing list
[hidden email]
http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs
Reply | Threaded
Open this post in threaded view
|

Re: Removing core-spec.pdf from repository?

Joachim Breitner-2
In reply to this post by Ben Gamari-3
Hi,

Am Montag, den 13.03.2017, 18:57 -0400 schrieb Ben Gamari:
> I suggest that we remove the PDF from the repository but instead I can
> start including it in my nightly documentation builds. Any objections?

I also dislike generated files in repos, but would like to point out
that there are a few pages out there that reference the link
https://github.com/ghc/ghc/blob/master/docs/core-spec/core-spec.pdf
directly; these would brake. But there is probably nothing we can
easily do about that.

Greetings,
Joachim

--
Joachim “nomeata” Breitner
  [hidden email]https://www.joachim-breitner.de/
  XMPP: [hidden email] • OpenPGP-Key: 0xF0FBF51F
  Debian Developer: [hidden email]
_______________________________________________
ghc-devs mailing list
[hidden email]
http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs

signature.asc (849 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Removing core-spec.pdf from repository?

Phil Ruffwind
> I also dislike generated files in repos, but would like to point out
> that there are a few pages out there that reference the link
> https://github.com/ghc/ghc/blob/master/docs/core-spec/core-spec.pdf
> directly; these would brake. But there is probably nothing we can
> easily do about that.

Could replace it with a plain text file that says: "MOVED to
https://XXX"
The build system could then be tweaked to output the .pdf somewhere else
so it would not overwrite this dummy file.
_______________________________________________
ghc-devs mailing list
[hidden email]
http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs
Reply | Threaded
Open this post in threaded view
|

Re: Removing core-spec.pdf from repository?

Richard Eisenberg-4
In reply to this post by Ben Gamari-3
Certainly no complaints from me. I knew I was doing a Bad Thing when I committed that file, but couldn't think of a good alternative, given the rarity of finding an ott installation.

Thanks, Ben.
Richard

> On Mar 13, 2017, at 6:57 PM, Ben Gamari <[hidden email]> wrote:
>
> Hello everyone,
>
> Currently there is a typeset copy of the Core specification in the GHC
> repository. This means any time someone changes the specification the
> repository grows by around 300kB. While this isn't the end of the
> world, it's generally considered bad form to put generated files under
> version control.
>
> Of course, the tools required to typeset the specification (ott and
> LaTeX) are non-trivial to install, so there is considerable convenience
> that comes from having a typeset version readily available.
>
> I suggest that we remove the PDF from the repository but instead I can
> start including it in my nightly documentation builds. Any objections?
>
> Cheers,
>
> - Ben
> _______________________________________________
> ghc-devs mailing list
> [hidden email]
> http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs

_______________________________________________
ghc-devs mailing list
[hidden email]
http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs
Reply | Threaded
Open this post in threaded view
|

Re: Removing core-spec.pdf from repository?

Mike Hewitt
In reply to this post by Phil Ruffwind
That would be a neat solution - I'd second that...


On 14/03/17 11:13, Phil Ruffwind wrote:

>> I also dislike generated files in repos, but would like to point out
>> that there are a few pages out there that reference the link
>> https://github.com/ghc/ghc/blob/master/docs/core-spec/core-spec.pdf
>> directly; these would brake. But there is probably nothing we can
>> easily do about that.
> Could replace it with a plain text file that says: "MOVED to
> https://XXX"
> The build system could then be tweaked to output the .pdf somewhere else
> so it would not overwrite this dummy file.
> _______________________________________________
> ghc-devs mailing list
> [hidden email]
> http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs

_______________________________________________
ghc-devs mailing list
[hidden email]
http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs
Reply | Threaded
Open this post in threaded view
|

Re: Removing core-spec.pdf from repository?

Takenobu Tani
In reply to this post by Ben Gamari-3
Hi devs,

How about putting it here every release? :
  https://downloads.haskell.org/~ghc/latest/docs/html/  or
  https://downloads.haskell.org/~ghc/latest/docs/

`core-spec.pdf` will be helpful.
But generating it in Windows is a bit complicated :)

Regards,
Takenobu


2017-03-14 7:57 GMT+09:00 Ben Gamari <[hidden email]>:
Hello everyone,

Currently there is a typeset copy of the Core specification in the GHC
repository. This means any time someone changes the specification the
repository grows by around 300kB. While this isn't the end of the
world, it's generally considered bad form to put generated files under
version control.

Of course, the tools required to typeset the specification (ott and
LaTeX) are non-trivial to install, so there is considerable convenience
that comes from having a typeset version readily available.

I suggest that we remove the PDF from the repository but instead I can
start including it in my nightly documentation builds. Any objections?

Cheers,

- Ben

_______________________________________________
ghc-devs mailing list
[hidden email]
http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs



_______________________________________________
ghc-devs mailing list
[hidden email]
http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs
Reply | Threaded
Open this post in threaded view
|

RE: Removing core-spec.pdf from repository?

GHC - devs mailing list
In reply to this post by Phil Ruffwind
It's very helpful to have a live, up to date PDF.  Not everyone has OTT, which is required to make it.  And OTT isn't available on Windows at all :-(

Simon

|  -----Original Message-----
|  From: ghc-devs [mailto:[hidden email]] On Behalf Of Phil
|  Ruffwind
|  Sent: 14 March 2017 00:14
|  To: [hidden email]
|  Subject: Re: Removing core-spec.pdf from repository?
|  
|  > I also dislike generated files in repos, but would like to point out
|  > that there are a few pages out there that reference the link
|  > https://github.com/ghc/ghc/blob/master/docs/core-spec/core-spec.pdf
|  > directly; these would brake. But there is probably nothing we can
|  > easily do about that.
|  
|  Could replace it with a plain text file that says: "MOVED to
|  https://XXX"
|  The build system could then be tweaked to output the .pdf somewhere
|  else so it would not overwrite this dummy file.
|  _______________________________________________
|  ghc-devs mailing list
|  [hidden email]
|  http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs
_______________________________________________
ghc-devs mailing list
[hidden email]
http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs
Reply | Threaded
Open this post in threaded view
|

Re: Removing core-spec.pdf from repository?

Elliot Cameron-2
The only loss is the ability to look at changes over time. If that's an important feature, you could write the files with a commit hash in the name. But that may not be worth it.

On Tue, Mar 14, 2017 at 4:38 AM, Simon Peyton Jones via ghc-devs <[hidden email]> wrote:
It's very helpful to have a live, up to date PDF.  Not everyone has OTT, which is required to make it.  And OTT isn't available on Windows at all :-(

Simon

|  -----Original Message-----
|  From: ghc-devs [mailto:[hidden email]] On Behalf Of Phil
|  Ruffwind
|  Sent: 14 March 2017 00:14
|  To: [hidden email]
|  Subject: Re: Removing core-spec.pdf from repository?
|
|  > I also dislike generated files in repos, but would like to point out
|  > that there are a few pages out there that reference the link
|  > https://github.com/ghc/ghc/blob/master/docs/core-spec/core-spec.pdf
|  > directly; these would brake. But there is probably nothing we can
|  > easily do about that.
|
|  Could replace it with a plain text file that says: "MOVED to
https://XXX"
|  The build system could then be tweaked to output the .pdf somewhere
|  else so it would not overwrite this dummy file.
|  _______________________________________________
|  ghc-devs mailing list
[hidden email]
http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs
_______________________________________________
ghc-devs mailing list
[hidden email]
http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs


_______________________________________________
ghc-devs mailing list
[hidden email]
http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs
Reply | Threaded
Open this post in threaded view
|

Re: Removing core-spec.pdf from repository?

Phil Ruffwind
On Tue, Mar 14, 2017, at 10:20, Elliot Cameron wrote:
> The only loss is the ability to look at changes over time.

GHC docs are archived for every version number:

https://downloads.haskell.org/~ghc/<version>/...

So it would remain possible to compare the changes between each release.
 The only problem is the discontinuity caused by this migration.
_______________________________________________
ghc-devs mailing list
[hidden email]
http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs