Orphaned logging page? Exclude included snippets from search index

[michaelstingl]

WHAT Needs to be Documented?

I found this with search: https://doc.owncloud.com/server/admin_manual/configuration/server/occ_command/logging_commands.html (but it's not part of the navigation)

@voroyam explained in https://github.com/owncloud/docs/issues/3591#issuecomment-848921819 , the occ page is a composite of many included files.

I'd propose to exclude such included snippets from the search index.

WHERE Does This Need To Be Documented (Link)?

?

WHY Should This Change Be Made?

Every page should have proper navigation. Individual included snippets are confusing.

(Optional) What Type Of Content Change Is This?

• [ ] New Content Addition
• [ ] Old Content Deprecation
• [ ] Existing Content Simplification
• [x] Bug Fix to Existing Content

(Optional) Which Manual Does This Relate To?

• [x] Admin Manual
• [ ] Developer Manual
• [ ] User Manual
• [ ] Android
• [ ] iOS
• [ ] Branded Clients
• [ ] Desktop Client
• [ ] Other

[cortho]

I found such a page as well - https://doc.owncloud.com/server/admin_manual/configuration/server/occ_command/integrity_check_commands.html I think the reason can be found in @voroyam 's comment https://github.com/owncloud/docs/issues/3191#issuecomment-786612468

Still, I'm not convinced by this answer

[voroyam]

My answer was regarding something I wanted to remove from the docs (or the branch of the docs) that are not maintained anymore, like 10.0 or 10.1.

The reason is that if you try to remove that - the build process will fail (if you want you can go back to the PR and check the drone logs). And to fix that you need manpower and try to convince someone that you want to fix something that is dead anyway. You won't get far.

This new find however is something else. I also have found several of those things, I think they are snippets that are included in a larger document, thus not required to be in the navigation bar on the left. Like if you go to the manual installation guide from @mmattel (the large one) there are a lot of those. Includes that navigate you to a different page that is not in the nav.adoc page.

My advice would be to always mention the NEW doc Team, @mmattel and @EParzefall when you have questions about the docs. They are in charge now.

[voroyam]

[voroyam]

Yeah, you have found the includes to the occ document. This was a change directed by Matthew and Martin, to split up the occ command document in to these kinds of includes.

[voroyam]

This is how the page looks included:

https://doc.owncloud.com/server/10.7/admin_manual/configuration/server/occ_command.html#logging-commands

[michaelstingl]

to split up the occ command document in to these kinds of includes.

Ah, I get the idea. Then we better exclude the includes from the search index… I updated title and top post.

[mmattel]

@voroyam is right, not each document is necessarily part of the navigation (but each document must be referenced bei either an xref or an include, else it is orphaned. We have to differenciate between referencing (xref) or including (include) a document. While xref just references a document, include does what it says and embeds a document into a page. Includes are a necessary procedure to keep big documents maintainable, like we have with the occ command set.

Building docs renders html files from all adoc files. When adoc files contain includes, the final html for this page contains all includes. This is what we see and by design not changable.

This now explains why indexing for ES shows pages, which are the origin of an include. The indexing logic behind is located at https://github.com/owncloud/docs/blob/901afc5f065c428023aad633f6f6c2d11dfb9aba/generator/generate-site.js#L38 and can be adopted - but there will be some effort behind to find the correct logic.

One idea may be post creating the htmls files, to create a map of indexable files (all unique files which are linked somewhere) and use them for ES.

@EParzefall FYI @JammingBen (FYI, heard that you have knowledge with ES)