You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@accumulo.apache.org by mikewalch <gi...@git.apache.org> on 2016/10/31 15:12:25 UTC
[GitHub] accumulo pull request #177: Embedded user manual within site
GitHub user mikewalch opened a pull request:
https://github.com/apache/accumulo/pull/177
Embedded user manual within site
* Created new pages for each release that show manual embedded in
site (using iframe)
* Left old (non-embedded) pages for historical reasons and due to anchor
tags not working with new pages
* Updated links in navbar to point to embedded manual
You can merge this pull request into a Git repository by running:
$ git pull https://github.com/mikewalch/accumulo manual-iframe
Alternatively you can review and apply these changes as the patch at:
https://github.com/apache/accumulo/pull/177.patch
To close this pull request, make a commit to your master/trunk branch
with (at least) the following in the commit message:
This closes #177
----
----
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] accumulo issue #177: Embedded user manual within site
Posted by ctubbsii <gi...@git.apache.org>.
Github user ctubbsii commented on the issue:
https://github.com/apache/accumulo/pull/177
Overall, I'm not convinced that it's better to have the manuals embedded into the site. It adds complexity to the site layout, and maintenance. It also has some side-effects: Links directly to the manual (which includes all of the links inside the manuals themselves) will still go to the raw, unwrapped version. It also makes it harder for users to right-click (or Ctrl-S) to save a copy of the manual.
While those issues aren't insurmountable, and the windowed look does look nice enough so far as it goes, I think maybe it's better to just open the manual in a separate window/tab. That's a much simpler way to address the navigation issue, is a much smaller change, and requires far less maintenance. That way, the manuals will continue to be thought of as separate, standalone items, which are independently downloadable and portable regardless of the website.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] accumulo issue #177: Embedded user manual within site
Posted by mikewalch <gi...@git.apache.org>.
Github user mikewalch commented on the issue:
https://github.com/apache/accumulo/pull/177
@ctubbsii, I pushed another commit 2f8d8255d1c3311bb517 that puts a warning above the manual telling users that the manual is embedded. It also links to the standalone manual. This lets users decide how they want to view manual (as I am sure some will prefer embedded and others standalone). Does that work?
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] accumulo pull request #177: Embedded user manual within site
Posted by mikewalch <gi...@git.apache.org>.
Github user mikewalch closed the pull request at:
https://github.com/apache/accumulo/pull/177
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] accumulo pull request #177: Embedded user manual within site
Posted by ctubbsii <gi...@git.apache.org>.
Github user ctubbsii commented on a diff in the pull request:
https://github.com/apache/accumulo/pull/177#discussion_r85815823
--- Diff: 1.5/examples/index.md ---
@@ -78,4 +78,4 @@ features of Apache Accumulo.
Also shows user permissions.
-[1]: {{ site.baseurl }}/1.5/accumulo_user_manual#_user_administration
+[1]: {{ site.baseurl }}/1.5/user-manual#_user_administration
--- End diff --
This doesn't necessarily account for all the external user section links, in the mailing list, on stack-overflow, etc.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] accumulo issue #177: Embedded user manual within site
Posted by ctubbsii <gi...@git.apache.org>.
Github user ctubbsii commented on the issue:
https://github.com/apache/accumulo/pull/177
I agree it makes sense to move the old ones so links go to the iframe version. Good point on the external hosting. We tend to update the manual between releases with typo and related fixes.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] accumulo issue #177: Embedded user manual within site
Posted by mikewalch <gi...@git.apache.org>.
Github user mikewalch commented on the issue:
https://github.com/apache/accumulo/pull/177
@ctubbsii, I like the idea of external hosting but the latest user manuals for 1.7 and 1.8 published on the website don't match the 1.8.0 and 1.7.2 releases published to maven central
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] accumulo issue #177: Embedded user manual within site
Posted by ctubbsii <gi...@git.apache.org>.
Github user ctubbsii commented on the issue:
https://github.com/apache/accumulo/pull/177
@mikewalch I think that change is better, but I don't think it changes my overall opinion. At this point, I'm `-0` (against, but not a veto), and would prefer a simpler change of making sure the manual opens in a new window/tab, and that the manual has a link back to the home page. But, my opinion is one of many. I defer to the majority.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] accumulo issue #177: Embedded user manual within site
Posted by ctubbsii <gi...@git.apache.org>.
Github user ctubbsii commented on the issue:
https://github.com/apache/accumulo/pull/177
Can you still create `#section` links when the manual is in the iframe?
We actually publish the manual to Maven Central. I'd almost rather serve the pages from there, and drop the additional hosting. Putting in the iframe may make it easier to do that, because we can make it look like we're still hosting it. If section links still work, it may be best to just wrap the manuals in their original locations, but link to the manual on Maven Central, rather than change the link in order to keep the unwrapped version at the previous location.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] accumulo pull request #177: Embedded user manual within site
Posted by mikewalch <gi...@git.apache.org>.
Github user mikewalch commented on a diff in the pull request:
https://github.com/apache/accumulo/pull/177#discussion_r85819482
--- Diff: 1.5/examples/index.md ---
@@ -78,4 +78,4 @@ features of Apache Accumulo.
Also shows user permissions.
-[1]: {{ site.baseurl }}/1.5/accumulo_user_manual#_user_administration
+[1]: {{ site.baseurl }}/1.5/user-manual#_user_administration
--- End diff --
`/1.5/accumulo_user_manual` still goes to the stand-alone manual so the links won't be broken. However, I could move rename the stand-alone manual and make `/1.5/accumulo_user_manual` the embedded manual (which is now `1.5/user-manual`). This makes sense to me now that I the '#section` links to work in the embedded manual due to 681f1ac9421ccd30dedd5db550d67e9842cc0a52
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---