8000 Provide documentation that is easy to browse online by f18m · Pull Request #995 · gperftools/gperftools · GitHub
[go: up one dir, main page]
More Web Proxy on the site http://driver.im/
Skip to content

Provide documentation that is easy to browse online #995

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Provide documentation that is easy to browse online #995

wants to merge 2 commits into from

Conversation

f18m
Copy link
@f18m f18m commented May 1, 2018

This is the new PR replacing
#952
with the git history cleaned up.

I reapplied changes after a fresh fork and tested installation with:

./autogen.sh
./configure
make dist
mv gperftools-2.6.3.tar.gz ~/tmp
cd ~/tmp
tar xvzf gperftools-2.6.3.tar.gz
cd gperftools-2.6.3
./configure
make install

@alk
Copy link
Contributor
alk commented May 5, 2018 •
edited
Loading

Thanks for your persistence. Couple more things. There is new line and non-portable rule pattern. I would apply this:

diff --git a/docs/Makefile.am b/docs/Makefile.am
index 4e3b3a8..bbe3476 100644
--- a/docs/Makefile.am
+++ b/docs/Makefile.am
@@ -76,7 +76,7 @@ MARKDOWN = pandoc --from markdown_github+pandoc_title_block --to html --standalo
 # Rule to convert markdown to HTML in 2 steps:
 # 1) convert markdown to HTML:
 # 2) convert markdown references to HTML ones:
-%.html: %.md
+.md.html:
        $(MARKDOWN) $< --output $@ ; sed -i 's@href="\(.*\).md"@href="\1.html"@g' $@
 
 HTML_FILES = \
@@ -98,4 +98,4 @@ endif
 install-data-hook:
        mkdir -p ${docdir}/images
        cp -fv $(ADDITIONAL_IMAGES) $(ADDITIONAL_IMAGE_DOTFILES) ${docdir}/images
-       
\ No newline at end of file
+

(there is trailing TAB in your patch)

But more importantly, install creates both README.md and readme.md to docs directory. This is going to be a problem on machines with case insensitive filesystem (AFAIK osex still defaults this way)

@f18m
Copy link
Author
f18m commented May 6, 2018

Hi alk,
I fixed the final TAB and the non-portable rule.
Regarding README.md: I have "fixed" the problem by simply not installing it: it's not converted to HTML format since it does not live under "docs" and after all the other readme.md/.html is perhaps a better summary of existing documentation pages.

Just 2 considerations:

  1. I think that nowadays installed documentation is not really used anymore: every developer I know looks at the main documentation pages provided online by the library/tool he's using. Indeed most projects nowadays don't even provide installable offline docs... so honestly I would not focus on that.
  2. the top-level README.md is perhaps too long as main project readme file: IMHO it contains stuff that should be moved under appropriate doc files and maybe updated (e.g., are the considerations under "64-BIT ISSUES" still so important to be placed in the main README?)

Just my 2 cents!
Thanks

@alk
Copy link
Contributor
alk commented May 13, 2018

Hm, while I agree that quite a bit of stuff in main README is stale, it is not useless at all. I do want it installed. Can we perhaps install html docs to separate dir ?

Also I am now getting warnings from pandoc. Dont think it was the case before, but not sure:

[WARNING] This document format requires a nonempty <title> element.
  Please specify either 'title' or 'pagetitle' in the metadata.
  Falling back to 'readme'

@alk
Copy link
Contributor
alk commented Aug 6, 2018

Apologies for delay. I think readme in top-level directly is worth installing. Can we just rename readme in docs directory to index?

@f18m
Copy link
Author
f18m commented Aug 6, 2018

Hi alk,
sorry for my delay too. I don't have much time to work on this in the short term future... if you can finish the last details I would be grateful... thanks.

@gperftools gperftools deleted a comment from sys-ptipu Jul 23, 2024
@gperftools gperftools deleted a comment from sys-ptipu Jul 23, 2024
@gperftools gperftools deleted a comment from sys-ptipu Jul 23, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers
No reviews
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
2 participants
@f18m @alk
0