[
https://issues.apache.org/jira/browse/SOLR-4957?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13693202#comment-13693202
]
Cassandra Targett edited comment on SOLR-4957 at 6/25/13 6:00 PM:
------------------------------------------------------------------
Comments about the specific problems found so far - there are other problems
I'll add in other comments.
bq. link checker plugin isn't installed/working
The page to check links needs two plugins to really use it:
# [Reporting
Plugin|https://marketplace.atlassian.com/plugins/net.customware.confluence.plugin.reporting].
This is a free plugin in Confluence 3.5.x, but moves to a pay model in
Confluence 4.x+. Once the Confluence upgrade is complete, this will stop
working again until ASF infra figures out the licensing for it, if they intend
to do that. It basically provides the structure of the page with page titles,
links to pages, and the links on those pages that either pass/fail the link
check.
# [Link Validator
Plugin|https://marketplace.atlassian.com/plugins/net.customware.confluence.plugin.linkvalidator]:
this is free, even after Confluence 4 & 5. However, the only thing it does on
its own is check the link it's given. It's the reporting plugin that actually
goes through all the pages to find the links to feed into the link validator.
Without the reporting plugin, all links need to be fed into this plugin
manually.
The report works OK - it's better than not having one at all, but it isn't
perfect. It often reports links as bad or unknown when they work just fine, but
I've only rarely seen it report a link as good that wasn't good. It checks all
the links every time the page is loaded, so if people are hitting it often, I
suspect that might cause a performance issue (not a major one for occasional
use - but if 100s or 1000s of users are loading the page every day, I wouldn't
be surprised to hear of a problem). In LucidWorks documentation, I hide the
link check page to everyone but myself, so if those plugins are installed, page
permissions should be set to a limited group.
bq. Unable to render embedded object: File (external-link-grey-gradient02.png)
not found.
Bah, my fault. At one time I had a little icon next to links as an indicator
that the link went somewhere other than another page of the Solr Ref Guide
(like, the link went to the Solr Wiki). It didn't export well into PDF at all -
it put the icon on it's own line instead of next to the link like it was
supposed to - so I later decided to remove it. I thought I'd scrubbed the pages
more thoroughly, but it looks like I didn't finish that before I exported. All
you need to do is add the little icon to the root page for now. Or, to remove
it entirely it's used exclusively in the Related Topics sections of the pages
it appears on (i.e., I never used it in the middle of a paragraph, only in the
lists of related links at the bottom of some pages).
The icon came from this site:
http://www.shapes4free.com/vector-icons/external-link-icons/. I was going to
upload the graphic here, but I checked the license and it said not to upload it
to another website. However, the graphics are free to use without attribution
or backlinks. Here is the full license: http://www.shapes4free.com/license/.
bq. Unknown macro: {topofpage}
That's a simple user macro that could be added. It adds HTML to the page to
link back to the top of a page, which is helpful for very long pages. An
alternative would be to just split those pages into smaller ones. Or, the macro
could easily be replaced with HTML code in the page, but for me a macro is
easier to use and remember. This one only works with the Documentation Theme,
which is what the Solr Ref Guide is using now.
In Confluence 3.5.x, go to User Macros in the Confluence Admin. Enter a name,
description, visibility to users, and what category it should appear in if
someone is browsing through the macro browser. Then select "No macro body"
under "Macro Body Processing", then HTML for "Output Format". In the Template
section add '<p style="text-align:right"><a href="#main">Back to Top</a></p>'.
Save and it's done.
In my tests, this converts fine with the upgrade to Confluence 4+ and the new
storage format. Because the higher Confluence versions are storing pages in
XHTML, and this is already HTML, there's no problem. The only thing that might
need to be modified is to add a line before the HTML code that says '##
@noparams'. I'm still learning these things in Confluence 4, but I believe that
says the macro has no parameters for a user to respond to and is required for
macros with no parameters.
Note, if a different space theme is used, the href target in the HTML would
need to be changed to '#content' instead of '#main'.
was (Author: ctargett):
Comments about the specific problems found so far - there are other
problems I'll add in other comments.
bq. link checker plugin isn't installed/working
The page to check links needs two plugins to really use it:
# [Reporting
Plugin|https://marketplace.atlassian.com/plugins/net.customware.confluence.plugin.reporting].
This is a free plugin in Confluence 3.5.x, but moves to a pay model in
Confluence 4.x+. Once the Confluence upgrade is complete, this will stop
working again until ASF infra figures out the licensing for it, if they intend
to do that. It basically provides the structure of the page with page titles,
links to pages, and the links on those pages that either pass/fail the link
check.
# [Link Validator
Plugin|https://marketplace.atlassian.com/plugins/net.customware.confluence.plugin.linkvalidator]:
this is free, even after Confluence 4 & 5. However, the only thing it does on
its own is check the link it's given. It's the reporting plugin that actually
goes through all the pages to find the links to feed into the link validator.
Without the reporting plugin, all links need to be fed into this plugin
manually.
The report works OK - it's better than not having one at all, but it isn't
perfect. It often reports links as bad or unknown when they work just fine, but
I've only rarely seen it report a link as good that wasn't good. It checks all
the links every time the page is loaded, so if people are hitting it often, I
suspect that might cause a performance issue (not a major one for occasional
use - but if 100s or 1000s of users are loading the page every day, I wouldn't
be surprised to hear of a problem). In LucidWorks documentation, I hide the
link check page to everyone but myself, so if those plugins are installed, page
permissions should be set to a limited group.
bq. Unable to render embedded object: File (external-link-grey-gradient02.png)
not found.
Bah, my fault. At one time I had a little icon next to links as an indicator
that the link went somewhere other than another page of the Solr Ref Guide
(like, the link went to the Solr Wiki). It didn't export well into PDF at all -
it put the icon on it's own line instead of next to the link like it was
supposed to - so I later decided to remove it. I thought I'd scrubbed the pages
more thoroughly, but it looks like I didn't finish that before I exported. All
you need to do is add the little icon to the root page for now. Or, to remove
it entirely it's used exclusively in the Related Topics sections of the pages
it appears on (i.e., I never used it in the middle of a paragraph, only in the
lists of related links at the bottom of some pages).
bq. Unknown macro: {topofpage}
That's a simple user macro that could be added. It adds HTML to the page to
link back to the top of a page, which is helpful for very long pages. An
alternative would be to just split those pages into smaller ones. Or, the macro
could easily be replaced with HTML code in the page, but for me a macro is
easier to use and remember. This one only works with the Documentation Theme,
which is what the Solr Ref Guide is using now.
In Confluence 3.5.x, go to User Macros in the Confluence Admin. Enter a name,
description, visibility to users, and what category it should appear in if
someone is browsing through the macro browser. Then select "No macro body"
under "Macro Body Processing", then HTML for "Output Format". In the Template
section add '<p style="text-align:right"><a href="#main">Back to Top</a></p>'.
Save and it's done.
In my tests, this converts fine with the upgrade to Confluence 4+ and the new
storage format. Because the higher Confluence versions are storing pages in
XHTML, and this is already HTML, there's no problem. The only thing that might
need to be modified is to add a line before the HTML code that says '##
@noparams'. I'm still learning these things in Confluence 4, but I believe that
says the macro has no parameters for a user to respond to and is required for
macros with no parameters.
Note, if a different space theme is used, the href target in the HTML would
need to be changed to '#content' instead of '#main'.
> Audit format/plugin/markup problems in solr ref guide related to Confluence
> 5.x upgrade
> ---------------------------------------------------------------------------------------
>
> Key: SOLR-4957
> URL: https://issues.apache.org/jira/browse/SOLR-4957
> Project: Solr
> Issue Type: Sub-task
> Components: documentation
> Reporter: Hoss Man
> Assignee: Hoss Man
>
> The Solr Ref guide donated by lucidworks is now live on the ASF's CWIKI
> instance of Confluence -- but the CWIKI is in the process of being upgraded
> to confluence 5.x (INFRA-6406)
> We need to audit the ref guide for markup/plugin/formatting problems that
> need to be fixed, but we should avoid making any major changes to try and
> address any problems like this until the Confluence 5.x upgrade is completed,
> since that process will involve the pages being "converted" to the newer wiki
> syntax at least twice, and may change the way some plugins work.
> We'll use this issue as a place for people to track any formating/plugin
> porblems they see when browsing the wiki -- please include the URL of the
> specific page(s) where problems are noticed, using relative anchors into
> individual page sections if possible, and a description of the problem seen.
--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators
For more information on JIRA, see: http://www.atlassian.com/software/jira
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@lucene.apache.org
For additional commands, e-mail: dev-h...@lucene.apache.org
