<div dir="ltr">Hello,<div><br></div><div>I was talking about the user manual. I imagine that the situation I was in is quite common---you've just implemented some small feature, and you want to write some documentation about it. While working on the documentation, I want to rebuild the manual quickly, so that I can see what it looks like, and make sure that links etc.</div><div><br></div><div>So I think it would be very important for Hadrian to have some high-level targets equivalent to the current `make html` etc. rather than having to ask it to rebuild a specific file somewhere in the build tree.</div><div><br></div><div>The confusion with my previous e-mail was caused because I hadn't realized what happens when building the documentation is disabled, namely:</div><div> 1. There are multiple places to check if the documentation is actually disabled</div><div> 2. When the documentation is disabled, the build targets disappear, rather than change their behavior to say "Docs are disabled, I am not going to build them, do X if you want them build".</div><div><br></div><div>So the issue is more of a usability one. </div><div><br></div><div>After I sent the e-mail to the list I realized that this all is documented online, so that's nice at least, but---in general---I think it would be nice if we could avoid such surprised, rather than having to document them in a separate place.</div><div><br></div><div>-Iavor</div><div><br></div><div><br></div><div><br></div><div><br></div><div><br></div><br><div class="gmail_quote"><div dir="ltr">On Wed, Nov 1, 2017 at 11:07 AM Patrick Dougherty <<a href="mailto:patrick.doc@ameritech.net" target="_blank">patrick.doc@ameritech.net</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="auto"><div><span></span></div><div><div></div><div>I spent some time with the docs this summer, and wrote a fair bit of the Hadrian documentation building code. So maybe I can shed some light.</div><div><br></div><div>The question is which docs do you want to build? The library documentation relies on the haddock executable, which is one of the last targets in the entire build. Also, IIRC, creating the nice links and references is somewhat tangled up with actually building the libraries. So it's not possible to avoid building GHC if you want the haddocks.</div><div><br></div><div>On the other hand, you can build just the user's guide using Hadrian. You can build any sphinx html target like this:</div><div><br></div><div>./build.sh _build/docs/html/users_guide/index.html</div><div><br></div><div>Or pdf with:</div><div><br></div><div><span style="background-color:rgba(255,255,255,0)">./build.sh _build/docs/pdfs/users_guide.pdf</span></div><div><br></div><div>While not the cleanest, it does work. So, I think the only way you can skip building GHC is using Hadrian for sphinx targets.</div><div><br></div><div>Until recently, the users guide did depend on building all of GHC.. I believe the make-based build just doesn't know about this change? I think I looked into updating it, but determined that it would be easier just to update Hadrian instead. I'm a little foggy on the details at this point. </div><div><br></div><div>Best,</div><div>Patrick</div></div></div><div dir="auto"><div><div><br>On Nov 1, 2017, at 7:13 AM, Andrey Mokhov <<a href="mailto:andrey.mokhov@newcastle..ac.uk" target="_blank">andrey.mokhov@newcastle.ac.uk</a>> wrote:<br><br></div></div></div><div dir="auto"><div><blockquote type="cite"><div><div class="m_4964773514586148526m_1772813240530011942WordSection1">
<p class="MsoNormal"><span style="color:#1f497d">> Maybe Hadrian will help here?<u></u><u></u></span></p>
<p class="MsoNormal"><span style="color:#1f497d"><u></u> <u></u></span></p>
</div></div></blockquote></div></div><div dir="auto"><div><blockquote type="cite"><div><div class="m_4964773514586148526m_1772813240530011942WordSection1"><p class="MsoNormal"><span style="color:#1f497d">Hadrian can build documentation in various formats but the current implementation is very coarse-grain: we either build all possible docs or no docs at all. It would be relatively easy
to add more fine-grain documentation targets and modes. If someone could design/describe the requirements in a ticket that would be great.<u></u><u></u></span></p></div></div></blockquote></div></div><div dir="auto"><div><blockquote type="cite"><div><div class="m_4964773514586148526m_1772813240530011942WordSection1">
<p class="MsoNormal"><span style="color:#1f497d"><u></u> <u></u></span></p>
<p class="MsoNormal"><span style="color:#1f497d">Cheers,<u></u><u></u></span></p>
<p class="MsoNormal"><span style="color:#1f497d">Andrey<u></u><u></u></span></p>
<p class="MsoNormal"><span style="color:#1f497d"><u></u> <u></u></span></p>
<p class="MsoNormal"><span style="color:#1f497d"><u></u> <u></u></span></p>
<div>
<div style="border:none;border-top:solid #e1e1e1 1.0pt;padding:3.0pt 0cm 0cm 0cm">
<p class="MsoNormal"><b><span lang="EN-US">From:</span></b><span lang="EN-US"> Simon Peyton Jones [<a href="mailto:simonpj@microsoft.com" target="_blank">mailto:simonpj@microsoft.com</a>]
<br>
<b>Sent:</b> 01 November 2017 08:28<br>
<b>To:</b> Iavor Diatchki <<a href="mailto:iavor.diatchki@gmail.com" target="_blank">iavor.diatchki@gmail.com</a>>; <a href="mailto:ghc-devs@haskell.org" target="_blank">ghc-devs@haskell.org</a>; Andrey Mokhov <<a href="mailto:andrey.mokhov@newcastle.ac.uk" target="_blank">andrey.mokhov@newcastle.ac.uk</a>><br>
<b>Subject:</b> RE: Building the docs, again<u></u><u></u></span></p>
</div>
</div>
<p class="MsoNormal"><u></u> <u></u></p>
</div></div></blockquote></div></div><div dir="auto"><div><blockquote type="cite"><div><div class="m_4964773514586148526m_1772813240530011942WordSection1"><p class="MsoNormal" style="margin-right:0cm;margin-bottom:6.0pt;margin-left:36.0pt">
It is quite confusing that we can be setting the same variable to different values in different places. It would also be quite helpful if we modified the Makefile to say `documentation build target is disabled` or some such, rather then going ahead and building
the whole of GHC, only at the end to inform me that it doesn't know what is `html`. <u></u><u></u></p></div></div></blockquote></div></div><div dir="auto"><div><blockquote type="cite"><div><div class="m_4964773514586148526m_1772813240530011942WordSection1">
<p class="MsoNormal"><span style="font-size:12.0pt">Maybe Hadrian will help here?<u></u><u></u></span></p>
<p class="MsoNormal"><span style="font-size:12.0pt"><u></u> <u></u></span></p>
<p class="MsoNormal"><span style="font-size:12.0pt">Simon<u></u><u></u></span></p>
<p class="MsoNormal"><span style="font-size:12.0pt"><u></u> <u></u></span></p>
<div>
<div>
<div style="border:none;border-top:solid #e1e1e1 1.0pt;padding:3.0pt 0cm 0cm 0cm">
<p class="MsoNormal"><b><span lang="EN-US">From:</span></b><span lang="EN-US"> ghc-devs [</span><a href="mailto:ghc-devs-bounces@haskell.org" target="_blank"><span lang="EN-US">mailto:ghc-devs-bounces@haskell.org</span></a><span lang="EN-US">]
<b>On Behalf Of </b>Iavor Diatchki<br>
<b>Sent:</b> 31 October 2017 21:49<br>
<b>To:</b> </span><a href="mailto:ghc-devs@haskell.org" target="_blank"><span lang="EN-US">ghc-devs@haskell.org</span></a><span lang="EN-US"><br>
<b>Subject:</b> Re: Building the docs, again<u></u><u></u></span></p>
</div>
</div>
<p class="MsoNormal"><u></u> <u></u></p>
<div>
<p class="MsoNormal" style="margin-right:0cm;margin-bottom:6.0pt;margin-left:0cm">
Hello,<u></u><u></u></p>
<div>
<p class="MsoNormal" style="margin-right:0cm;margin-bottom:6.0pt;margin-left:0cm">
<u></u> <u></u></p>
</div>
<div>
<p class="MsoNormal" style="margin-right:0cm;margin-bottom:6.0pt;margin-left:0cm">
never mind, I figured it out---apparently the build targets were disabled for the `quick` flavor, which I was using. <u></u><u></u></p>
</div>
<div>
<p class="MsoNormal" style="margin-right:0cm;margin-bottom:6.0pt;margin-left:0cm">
<u></u> <u></u></p>
</div>
<div>
<p class="MsoNormal" style="margin-right:0cm;margin-bottom:6.0pt;margin-left:0cm">
It is quite confusing that we can be setting the same variable to different values in different places. It would also be quite helpful if we modified the Makefile to say `documentation build target is disabled` or some such, rather then going ahead and building
the whole of GHC, only at the end to inform me that it doesn't know what is `html`. <u></u><u></u></p>
</div>
<div>
<p class="MsoNormal" style="margin-right:0cm;margin-bottom:6.0pt;margin-left:0cm">
<u></u> <u></u></p>
</div>
<div>
<p class="MsoNormal" style="margin-right:0cm;margin-bottom:6.0pt;margin-left:0cm">
-Iavor<u></u><u></u></p>
</div>
<div>
<p class="MsoNormal" style="margin-right:0cm;margin-bottom:6.0pt;margin-left:0cm">
<u></u> <u></u></p>
</div>
<div>
<p class="MsoNormal" style="margin-right:0cm;margin-bottom:6.0pt;margin-left:0cm">
<u></u> <u></u></p>
</div>
</div>
<p class="MsoNormal" style="margin-right:0cm;margin-bottom:6.0pt;margin-left:0cm">
<u></u> <u></u></p>
<div>
<div>
<p class="MsoNormal" style="margin-right:0cm;margin-bottom:6.0pt;margin-left:0cm">
On Tue, Oct 31, 2017 at 2:26 PM Iavor Diatchki <<a href="mailto:iavor.diatchki@gmail.com" target="_blank">iavor.diatchki@gmail.com</a>> wrote:<u></u><u></u></p>
</div>
<blockquote style="border:none;border-left:solid #cccccc 1.0pt;padding:0cm 0cm 0cm 6.0pt;margin-left:4.8pt;margin-top:5.0pt;margin-right:0cm;margin-bottom:5.0pt">
<div>
<p class="MsoNormal" style="margin-right:0cm;margin-bottom:6.0pt;margin-left:0cm">
Hello,<u></u><u></u></p>
<div>
<p class="MsoNormal" style="margin-right:0cm;margin-bottom:6.0pt;margin-left:0cm">
<u></u> <u></u></p>
</div>
<div>
<p class="MsoNormal" style="margin-right:0cm;margin-bottom:6.0pt;margin-left:0cm">
sometime ago, I asked if it is possible to build just the GHC docs, without building the compiler. I was told to just run `make html`. This does not appear to work, the command seems to just start building GHC. What am I doing wrong?<u></u><u></u></p>
</div>
<div>
<p class="MsoNormal" style="margin-right:0cm;margin-bottom:6.0pt;margin-left:0cm">
<u></u> <u></u></p>
</div>
<div>
<p class="MsoNormal" style="margin-right:0cm;margin-bottom:6.0pt;margin-left:0cm">
Here is the output I see, running the command from the root of the GHC tree.<u></u><u></u></p>
</div>
<div>
<p class="MsoNormal" style="margin-right:0cm;margin-bottom:6.0pt;margin-left:0cm">
<u></u> <u></u></p>
</div>
<div>
<div>
<p class="MsoNormal" style="margin-right:0cm;margin-bottom:6.0pt;margin-left:0cm">
> make html V=0<u></u><u></u></p>
</div>
<div>
<p class="MsoNormal" style="margin-right:0cm;margin-bottom:6.0pt;margin-left:0cm">
===--- building phase 0<u></u><u></u></p>
</div>
<div>
<p class="MsoNormal" style="margin-right:0cm;margin-bottom:6.0pt;margin-left:0cm">
make --no-print-directory -f <a href="https://na01.safelinks.protection.outlook.com/?url=http%3A%2F%2Fghc.mk&data=02%7C01%7Csimonpj%40microsoft.com%7Cf681d88b258e48157e2008d520a95302%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C636450833981966485&sdata=qPWSl5FMtQ%2FRzTI8PYxHfkK%2B%2FltgBh2z1VRr8dJleok%3D&reserved=0" target="_blank">
ghc.mk</a> phase=0 phase_0_builds<u></u><u></u></p>
</div>
<div>
<p class="MsoNormal" style="margin-right:0cm;margin-bottom:6.0pt;margin-left:0cm">
make[1]: Nothing to be done for 'phase_0_builds'.<u></u><u></u></p>
</div>
<div>
<p class="MsoNormal" style="margin-right:0cm;margin-bottom:6.0pt;margin-left:0cm">
===--- building phase 1<u></u><u></u></p>
</div>
<div>
<p class="MsoNormal" style="margin-right:0cm;margin-bottom:6.0pt;margin-left:0cm">
make --no-print-directory -f <a href="https://na01.safelinks.protection.outlook.com/?url=http%3A%2F%2Fghc.mk&data=02%7C01%7Csimonpj%40microsoft.com%7Cf681d88b258e48157e2008d520a95302%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C636450833981966485&sdata=qPWSl5FMtQ%2FRzTI8PYxHfkK%2B%2FltgBh2z1VRr8dJleok%3D&reserved=0" target="_blank">
ghc.mk</a> phase=1 phase_1_builds<u></u><u></u></p>
</div>
<div>
<p class="MsoNormal" style="margin-right:0cm;margin-bottom:6.0pt;margin-left:0cm">
HC [stage 0] compiler/stage1/build/BufWrite.o<u></u><u></u></p>
</div>
<div>
<p class="MsoNormal" style="margin-right:0cm;margin-bottom:6.0pt;margin-left:0cm">
HC [stage 0] compiler/stage1/build/Pretty.o<u></u><u></u></p>
</div>
<div>
<p class="MsoNormal" style="margin-right:0cm;margin-bottom:6.0pt;margin-left:0cm">
compilation IS NOT required<u></u><u></u></p>
</div>
<div>
<p class="MsoNormal" style="margin-right:0cm;margin-bottom:6.0pt;margin-left:0cm">
HC [stage 0] compiler/stage1/build/PprColour.o<u></u><u></u></p>
</div>
<div>
<p class="MsoNormal" style="margin-right:0cm;margin-bottom:6.0pt;margin-left:0cm">
compilation IS NOT required<u></u><u></u></p>
</div>
<div>
<p class="MsoNormal" style="margin-right:0cm;margin-bottom:6.0pt;margin-left:0cm">
HC [stage 0] compiler/stage1/build/Outputable.o<u></u><u></u></p>
</div>
<div>
<p class="MsoNormal" style="margin-right:0cm;margin-bottom:6.0pt;margin-left:0cm">
compilation IS NOT required<u></u><u></u></p>
</div>
<div>
<p class="MsoNormal" style="margin-right:0cm;margin-bottom:6.0pt;margin-left:0cm">
HC [stage 0] compiler/stage1/build/Json.o<u></u><u></u></p>
</div>
<div>
<p class="MsoNormal" style="margin-right:0cm;margin-bottom:6.0pt;margin-left:0cm">
compilation IS NOT required<u></u><u></u></p>
</div>
<div>
<p class="MsoNormal" style="margin-right:0cm;margin-bottom:6.0pt;margin-left:0cm">
HC [stage 0] compiler/stage1/build/SrcLoc.o<u></u><u></u></p>
</div>
<div>
<p class="MsoNormal" style="margin-right:0cm;margin-bottom:6.0pt;margin-left:0cm">
compilation IS NOT required<u></u><u></u></p>
</div>
<div>
<p class="MsoNormal" style="margin-right:0cm;margin-bottom:6.0pt;margin-left:0cm">
HC [stage 0] compiler/stage1/build/BasicTypes.o<u></u><u></u></p>
</div>
<div>
<p class="MsoNormal" style="margin-right:0cm;margin-bottom:6.0pt;margin-left:0cm">
compilation IS NOT required<u></u><u></u></p>
</div>
<div>
<p class="MsoNormal" style="margin-right:0cm;margin-bottom:6.0pt;margin-left:0cm">
HC [stage 0] compiler/stage1/build/Unique.o<u></u><u></u></p>
</div>
<div>
<p class="MsoNormal" style="margin-right:0cm;margin-bottom:6.0pt;margin-left:0cm">
HC [stage 0] compiler/stage1/build/Packages.o-boot<u></u><u></u></p>
</div>
<div>
<p class="MsoNormal" style="margin-right:0cm;margin-bottom:6.0pt;margin-left:0cm">
compilation IS NOT required<u></u><u></u></p>
</div>
<div>
<p class="MsoNormal" style="margin-right:0cm;margin-bottom:6.0pt;margin-left:0cm">
HC [stage 0] compiler/stage1/build/FiniteMap.o<u></u><u></u></p>
</div>
<div>
<p class="MsoNormal" style="margin-right:0cm;margin-bottom:6.0pt;margin-left:0cm">
compilation IS NOT required<u></u><u></u></p>
</div>
<div>
<p class="MsoNormal" style="margin-right:0cm;margin-bottom:6.0pt;margin-left:0cm">
HC [stage 0] compiler/stage1/build/Name.o-boot<u></u><u></u></p>
</div>
</div>
<div>
<p class="MsoNormal" style="margin-right:0cm;margin-bottom:6.0pt;margin-left:0cm">
<u></u> <u></u></p>
</div>
<div>
<p class="MsoNormal" style="margin-right:0cm;margin-bottom:6.0pt;margin-left:0cm">
(then I interrupted it).<u></u><u></u></p>
</div>
<div>
<p class="MsoNormal" style="margin-right:0cm;margin-bottom:6.0pt;margin-left:0cm">
<u></u> <u></u></p>
</div>
<div>
<p class="MsoNormal" style="margin-right:0cm;margin-bottom:6.0pt;margin-left:0cm">
Also, in `mk/<a href="https://na01.safelinks.protection.outlook.com/?url=http%3A%2F%2Fconfig.mk&data=02%7C01%7Csimonpj%40microsoft.com%7Cf681d88b258e48157e2008d520a95302%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C636450833981966485&sdata=F9gkJnWKkFVjF0ZgraTEyQXPnOA4Id2lL7jhppN1mrc%3D&reserved=0" target="_blank">config.mk</a>`
I see this:<u></u><u></u></p>
</div>
<div>
<div>
<p class="MsoNormal" style="margin-right:0cm;margin-bottom:6.0pt;margin-left:0cm">
BUILD_SPHINX_HTML = YES<u></u><u></u></p>
</div>
</div>
</div>
<div>
<div>
<p class="MsoNormal" style="margin-right:0cm;margin-bottom:6.0pt;margin-left:0cm">
<u></u> <u></u></p>
</div>
<div>
<p class="MsoNormal" style="margin-right:0cm;margin-bottom:6.0pt;margin-left:0cm">
-Iavor<u></u><u></u></p>
</div>
<div>
<p class="MsoNormal" style="margin-right:0cm;margin-bottom:6.0pt;margin-left:0cm">
<u></u> <u></u></p>
</div>
<div>
<p class="MsoNormal" style="margin-right:0cm;margin-bottom:6.0pt;margin-left:0cm">
<u></u> <u></u></p>
</div>
<div>
<p class="MsoNormal" style="margin-right:0cm;margin-bottom:6.0pt;margin-left:0cm">
<u></u> <u></u></p>
</div>
</div>
</blockquote>
</div>
</div>
</div></div></blockquote></div></div><div dir="auto"><div><blockquote type="cite"><div><div class="m_4964773514586148526m_1772813240530011942WordSection1"></div>
</div></blockquote><blockquote type="cite"><div><span>_______________________________________________</span><br><span>ghc-devs mailing list</span><br><span><a href="mailto:ghc-devs@haskell.org" target="_blank">ghc-devs@haskell.org</a></span><br><span><a href="http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs" target="_blank">http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs</a></span><br></div></blockquote></div></div></blockquote></div></div>