vy commented on PR #2427: URL: https://github.com/apache/logging-log4j2/pull/2427#issuecomment-2033861605
@garydgregory shared [some remarks in Slack](https://the-asf.slack.com/archives/C4TQW0M5L/p1712094446443179). I will address them here. > I get a 404 for the API and Implementation Javadocs. Right. Fixed in 391e4ce2ae57152f144a5a6ed800d30d4713e90f. > The MongoDB page linked from the left-hand menu is missing all the information from the current site. There is no MongoDB 3 either. This makes me wonder what else is missing. It is not missing any. It has the identical content that we have today: https://web.archive.org/web/20231225134825/https://logging.apache.org/log4j/2.x/log4j-mongodb4.html If you are looking for the one in `Manual > Appenders > NoSQLAppenderMongoDB4`, it is still there. > JMS Appender is… where? OMG, all the Appenders are ALL buried on ONE page: plugin-reference. Yikes. I expect to see a left-hand menu item for each Appender, Layout, and so on, just like the current site. Gary, I think you have a misunderstanding. Let me try to clarify certain things. 1. _Components_ [left] menu in Antora is identical to the one we have today. You can browse to our current website (see the _Components_ menu section on left?) and compare it yourself. If you find a difference, I would be happy to correct them. 1. We still have hand-written pages for appenders, layouts, filters, etc. in the manual. They are exactly at their same URL, nothing changed. 1. Plugin reference, as it is stated at the beginning of that page, is _Javadoc-on-steroids_. Instead of a fully-blown Javadoc of individual modules, it combines all modules and only exposes plugin-related information and nothing else. Right now, we have a Javadoc in `FooAppender.java` and a section for `Foo appender` in `appenders.adoc`. Plugin reference enables us to consolidate this information in one place: Javadoc of `FooAppender`. This not only helps with avoiding to duplicate the documentation effort, but also captures the configuration parameters precisely right from the sources. No more _"Oh, source code actually has a `timeoutMillis` field, but it is incorrectly documented as `timeout`"_, or _"Oh, there is actually a `timeoutMillis` field the user is asking for, but it is not even documented"_, etc. > Based on the above, IMO, you don’t need both a separate Manual and a Plugin Reference as siblings in the left-hand menu. A reference should be IN a manual. Yes, and no. Plugin reference is generated from the source code. It might not contain the most easy-to-understand introduction. OTOH, manual is hand-written. @ppkarwasz and my long-term plan is to link to plugin reference from manual, instead of duplicating the content there. For instance, manual should not explain the configuration options of `PatternLayout`, instead give a brief explanation, share some use cases, examples, etc., and point to the plugin reference for details. > Regardless, I should still be able to drill down the left-hand menu for all features. `2.x-docgen-antora` structure is identical to what we have today. We are not worsening the situation. If you think it can be improved, sure, please go ahead. But I don't find this a blocker for this particular PR. > The red styling for code is bad IMO. For me read == error. No IDEs I know use red code Strings for example. Right. I will see what I can do about it. > It’s a bummer that the left hand side menu tree is always redrawn as (mostly?) collapsed, I want to leave the nodes I opened open! Agreed. That is a styling issue, and I prefer to tackle that later on. > It’s a bit odd to have a top-level menu item called “Get”, instead of “Download”. Yes, because I wanted it to contain the following sub-menus: * Download * Runtime dependencies * Release notes Since, there is already a `Download`, I cannot call it `Download`. If you have a better suggestion, please say so. > Sometimes XML is styled, sometimes it is not (the FAQ page for example) Right. This is due to the fact that the original source (Markdown, XDoc, etc.) was not indicating the language. I fixed whatever I can find in 234ac805d8c5e426958f6c5e06b9dcfbc9652cb7. > “Internal components” is not good, I would say that one is not supposed to use “Internal components”, a better name might be “Log4j components” or “Self-hosted components” (kinda lame) Improved the navigation in 205f61725a081dba8ba83978d2c724491b87db00. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: notifications-unsubscr...@logging.apache.org For queries about this service, please contact Infrastructure at: us...@infra.apache.org
