Document use of implementation files

[GoogleCodeExporter]

The current readme says that the various file mappings are hardcoded, but 
http://code.google.com/p/include-what-you-use/source/detail?r=374 changed that. 
It appears that, lacking additional arguments, the .imp files are not installed 
anywhere, not included in the binary, and not used.

See discussion in 
https://groups.google.com/d/topic/include-what-you-use/SF-UFsedHIk/discussion

Original issue reported on code.google.com by ryan.pav...@gmail.com on 26 Nov 2012 at 7:27

[GoogleCodeExporter]

Sure, I'd be happy to do that. I will be proposing some more changes to the 
mapping  file implementation, though, so I might punt until the dust has 
settled.

Original comment by kim.gras...@gmail.com on 27 Nov 2012 at 5:04

[GoogleCodeExporter]

Hmm. There's enormous overlap between the readme and the wiki, and the wiki is 
definitely more up-to-date. Do we need to maintain both?

Original comment by kim.gras...@gmail.com on 10 Dec 2012 at 1:03

[GoogleCodeExporter]

It sounds wrong, but I think that we should maintain both. Both are useful and 
I don't want to drop any of them.

Original comment by vsap...@gmail.com on 16 Dec 2012 at 11:31

[GoogleCodeExporter]

I'm considering generating the README from the wiki sources. Would that be 
acceptable? It looks like a simple matter of Python programming...

Original comment by kim.gras...@gmail.com on 26 Dec 2012 at 9:11

[GoogleCodeExporter]

OK, here's a README generator that seems to work from the current wiki sources.

I'm considering committing this to the wiki/ SVN directory at 
http://code.google.com/p/include-what-you-use/source/browse/#svn%2Fwiki.

If this strategy makes sense to anyone else, I'll try and go through the 
current README and transcribe anything extra from there to the wiki, and then 
regenerate it from the wiki directly.

Original comment by kim.gras...@gmail.com on 27 Dec 2012 at 5:38

Attachments:

• make_readme.py

[GoogleCodeExporter]

Here's an example of a README generated from the wiki entries (after quite a 
lot of editing to normalize the style of the wiki markup).

A real README should maybe contain a little heading with a reference back to 
the wiki, but for being auto-generated, I don't think this is bad.

I'd be most grateful for any comments!

(ryan.pavlik: sorry I'm hijacking this issue for this exercise, but as soon as 
I have  a documentation master, I can start trying to make it more coherent.)

Original comment by kim.gras...@gmail.com on 27 Dec 2012 at 8:29

Attachments:

• readme.txt

[GoogleCodeExporter]

Thanks, Kim. readme.txt looks good, but I have a few comments.
- First paragraphs of 'Why Include What You Use?' and 'Instructions for Users' 
tell the same, but in slightly different words.
- Empty lines around headers and code blocks are inconsistent. Sometimes there 
is 1 empty line before, 1 line after; sometimes 2 and 1; sometimes 2 and 0.

Please add a header to make_readme.py.

Original comment by vsap...@gmail.com on 30 Dec 2012 at 9:32

[GoogleCodeExporter]

Thank you!

I mostly posted this to get an idea of whether auto-generating README was 
feasible.

- Redundancy -- yes, these paragraphs come up in different guises between the 
README and various wiki pages. I was planning to unify them.
- Formatting -- I noticed that, too. If I can make the script format code block 
uniformly, I will, but I'll probably just edit the wiki pages to be consistent.
- File header -- thanks, that didn't occur to me!

I'll post back a new patch as soon as I can find time to address this.

Original comment by kim.gras...@gmail.com on 31 Dec 2012 at 9:12

[GoogleCodeExporter]

Here's a revised version of make_readme.py -- I can commit it myself, to the 
wiki/ subdirectory, if it looks good as-is.

I'll address the actual Wiki content then, and finally regenerate a new README 
for review.

Original comment by kim.gras...@gmail.com on 31 Dec 2012 at 12:56

Attachments:

• make_readme.py

[GoogleCodeExporter]

make_readme.py looks good to me.

Original comment by vsap...@gmail.com on 2 Jan 2013 at 9:33

[GoogleCodeExporter]

It turns out I can't commit to the wiki/ subdirectory, it's probably reserved 
for edits through the web UI. Could you commit make_readme.py for me in the 
include-what-you-use root?

Thanks!

Original comment by kim.gras...@gmail.com on 2 Jan 2013 at 11:09

[GoogleCodeExporter]

Argh. Here's the patch.

Original comment by kim.gras...@gmail.com on 2 Jan 2013 at 11:09

Attachments:

• make_readme.patch

[GoogleCodeExporter]

Here's a new Wiki page on IWYU mappings, for review:
http://code.google.com/p/include-what-you-use/wiki/IWYUMappings

I've tried to cover all interesting aspects. Let me know if anything is unclear!

Once this is OK, I'll edit the current content to refer here where it makes 
sense.

Original comment by kim.gras...@gmail.com on 6 Jan 2013 at 9:47

[GoogleCodeExporter]

Sorry, haven't noticed before that Python scripts use 2-spaces indentation, not 
4-spaces. Kim, can you adjust make_readme.py?

IWYUMappings looks fine.

Original comment by vsap...@gmail.com on 13 Jan 2013 at 9:28

[GoogleCodeExporter]

Good catch, I didn't see that! Here's an updated patch, ran it through PEP8 and 
Pylint and fixed some minor issues.

Original comment by kim.gras...@gmail.com on 13 Jan 2013 at 9:43

Attachments:

• make_readme.patch

[GoogleCodeExporter]

make_readme.py looks good to me, feel free to commit.

Original comment by vsap...@gmail.com on 14 Jan 2013 at 9:04

[GoogleCodeExporter]

Thanks! Done in r432.

Attached is a README generated from the current Wiki contents. Let me know if 
it's OK to commit and, ryan.pavlik, if it addresses your concerns.

Original comment by kim.gras...@gmail.com on 14 Jan 2013 at 8:12

Attachments:

• README.txt

[GoogleCodeExporter]

README looks fine to me. A few tweaks:
  - s/Include what you use/Include-what-you-use/ in How to Build section
  - how hard is it to make build instructions a numbered list? Because # as list item marker and # as a comment start are pretty confusing. Don't waste too much time to do this programmatically, I am OK with using explicitly 1., 2. in wiki

Some out-of-tree build instructions are missing, but I think we can add them 
back when out-of-tree build is supported better.

Original comment by vsap...@gmail.com on 20 Jan 2013 at 5:54

[GoogleCodeExporter]

Thanks!

- Edited the Wiki to address these content issues.
- The script is strictly line-oriented, so numbered lists are hard to solve, 
I've thought about it briefly before. I changed the wiki to use bullet points 
for the most part, and increased indentation for the code sample in bullet list.
- Fixed script so it explicitly emits UTC time, otherwise the generated time 
would have been ambiguous.
- Added brief descriptions of all source files to Instructions for Developers 
(Ryan asked about this somewhere else.)

Attached is an updated README -- I'm pretty happy with it. I'm guessing it's OK 
to commit?

Original comment by kim.gras...@gmail.com on 20 Jan 2013 at 9:03

Attachments:

• README.txt

[GoogleCodeExporter]

Yes, OK to commit.

Original comment by vsap...@gmail.com on 20 Jan 2013 at 10:55

[GoogleCodeExporter]

New README committed in r440. ryan.pavlik, can you please look this over and 
let me know if it's OK by you? I think this addresses your concerns (and more), 
but I want to be sure.

Original comment by kim.gras...@gmail.com on 21 Jan 2013 at 4:46

• Changed state: Accepted

[GoogleCodeExporter]

Looks good to me! Super cool!

Original comment by ryan.pav...@gmail.com on 1 Feb 2013 at 9:48

[GoogleCodeExporter]

Thanks, closing the bug!

Original comment by kim.gras...@gmail.com on 1 Feb 2013 at 9:50

• Changed state: Fixed