<div dir="ltr">What about standardizing on an 'experimental' prefix such as <font color="#500050" face="arial, sans-serif"><span style="font-size:12.499999046325684px">-fx-use-rpaths or -fx-kill-oneshot? These flags would not be added to the user guide and their intent clear when actually using them.</span></font><div><div class="gmail_extra"><br><div class="gmail_quote">On Thu, Nov 6, 2014 at 10:28 AM, Simon Marlow <span dir="ltr"><<a href="mailto:marlowsd@gmail.com" target="_blank">marlowsd@gmail.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><span class="">On 06/11/2014 12:06, Jan Stolarek wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
Devs,<br>
<br>
I have some important information for everyone.<br>
<br>
TL;DR1 As a rule of thumb, whenever you modify DynFlags or StaticFlags please<br>
make absolutely sure that your changes are described in the User's Guide. See<br>
Note [Updating flag description in the User's Guide] in DynFlags.<br>
<br>
TL;DR2 Your help is needed to update the User's Guide.<br>
<br>
I've spent last two days on updating the flag descriptions in the User's Guide<br>
(#9358). Saying that things were a complete mess would be an understatement. We<br>
had lots of flags that were not documented in the user's guide, we had<br>
documentation for flags that no longer exist, lots of flags were incorrectly<br>
labeled as static, etc. It seems that we don't have a habit of updating User's<br>
Guide when we change the code responsible for flags. I updated huge chunks of<br>
the documentation and things are in a better shape now. But if we forget to<br>
update documentation when we make changes then in 2 or 3 years things will most<br>
likely be as bad as they were before my clean-up. I added a Note and lots of<br>
references to it to remind us about that. If things go well we might even have a<br>
Herald rule to remind about updating User's Guide whenever DynFlags and<br>
StaticFlags are modified by a commit/revision [1].<br>
</blockquote>
<br></span>
Your efforts are much appreciated, thankyou :)<span class=""><br>
<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
These flags are currently completely missing from the User's Guide:<br>
<br>
-fbuilding-cabal-package<br>
-fflat-cache<br>
-fhpc-no-auto<br>
-fkill-absence<br>
-fkill-one-shot<br>
-fsimple-list-literals<br>
-fspecialise-aggressively<br>
-fuse-rpaths<br>
-fspec-constr-recursive<br>
-ffloat-lam-args<br>
-ffloat-all-lams<br>
</blockquote>
<br></span>
Sometimes we add flags that are for experimentation or development purposes and not intended for user consumption, and these tend not to be added to the User's Guide. I suspect many of the flags you mention fall into this category. I suggest for these we have a specific comment in the source "developer use only; undocumented" so that we know they don't need to go in the User's Guide.<span class=""><br>
<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
For these flags Flag Reference section provides the description of their -fno-*<br>
version:<br>
<br>
-fembed-manifest<br>
-fgen-manifest<br>
-fghci-history<br>
-fghci-sandbox<br>
-fpre-inlining<br>
-fprint-bind-contents<br>
-fprof-count-entries<br>
-fshared-implib<br>
<br>
This seems to go against our convention of describing the flags. Should we<br>
revert to desribing their normal version (ie. ones that enable something, not<br>
disable)?<br>
</blockquote>
<br></span>
Flags that are on by default we often document the no- version deliberately, because this is the form the user is most likely to want. Documenting the positive version sounds strange and is likely to be confusing. I'm surprised you didn't include -fomit-yields here.<span class=""><br>
<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
As part of my work I also removed -ddump-core-pipeline and -ddump-simpl-phases,<br>
</blockquote>
<br></span>
isn't -ddump-simpl-phases useful? what's the other way to do that?<br>
<br>
Cheers,<br>
Simon<div class="HOEnZb"><div class="h5"><br>
______________________________<u></u>_________________<br>
ghc-devs mailing list<br>
<a href="mailto:ghc-devs@haskell.org" target="_blank">ghc-devs@haskell.org</a><br>
<a href="http://www.haskell.org/mailman/listinfo/ghc-devs" target="_blank">http://www.haskell.org/<u></u>mailman/listinfo/ghc-devs</a><br>
</div></div></blockquote></div><br></div></div></div>