Cacti / documentation

Documentation for Cacti, Spine, RRDProxy and more
61 stars 52 forks source link

Spikekill addition #82

Closed riversdev0 closed 4 years ago

riversdev0 commented 4 years ago

I can certainly conform this document to the standards you outlined, but kindly allow me to ask the motivation for these standards. In my exploration, the formatting of the document I contributed (as viewed in HTML) appears identical to that of other documents in the repository. I'm wondering if perhaps you desire to keep the markdown version pristine for a scenario in which people read the documentation from text file, rather than from HTML on GitHub. I'm willing to contribute in the correct ways, but it's also helpful to understand the drivers behind the standards.

I don't see any lines with spaces at the front of them. Can you kindly point them out to me so I can fix them?

I will modify the doc and open another pull request.

netniV commented 4 years ago

Yes, it is for that reason as people can read these at a command line then. Yes, there have been lapse in the documentation as not everyone has adhered to it though I, personally, do try and highlight areas. In theory, there should be a build failure if the document doesn't conform but some are more our styles than lint-able issues.

netniV commented 4 years ago

image This image shows what I saw. Looking more closely thanks to your comments, I can see this is a web formatting issue because of the long line length. So, once the line length is corrected, it would resolve the layout issue I saw.

For example

Spikekill requires certain values to successfully calculate which data points to overwrite.  The following settings are customizable:
1. Replacement Method - When Spikekill identifies data points to overwrite, the value of _Replacement Method_ represents the data that will be written in place of each data point

Should really be the following once the line spacing and wrapping is sorted.

Spikekill requires certain values to successfully calculate which data points to
overwrite.  The following settings are customizable:

1. Replacement Method - When Spikekill identifies data points to overwrite, the
   value of _Replacement Method_ represents the data that will be written in
   place of each data point

If you do spot other documents that need to be updated, feel free to post a PR for them too or raise an issue tracker for it so it can be sorted out 👍 Documentation is unfortunately the last thing to get updated as we are using all our free time on the code itself.

Really appreciate the comments/contributions, keep them flowing 👍

riversdev0 commented 4 years ago

Thank you for the feedback. I've got the doco updated now, I'll submit a PR when you answer this last question. When I manually wrap lines in a text file like this, I normally leave a space hanging at the end of the line right before the line break. I do this because when I edit the paragraph in the future, I don't have to join each line with a "backspace" and a "spacebar", rather just with a "backspace". Do you want the space left at the end of the lines, or not?

netniV commented 4 years ago

Sorry, must have missed that one, there shouldn't be no.

I believe that actually breaks one of the styling rules that is caught but either way we do remove those normally. The editor nano tended to leave those if you use them as I have a bash script which detects if I'm editing an MD file and then sets the -j 80 parameter (at least that's what I think it is off the top of my head without going digging). They have now added a new parameter to strip those extra spaces in later versions though I still have to remove them as my script is used across multiple systems that don't all have the updated version of nano yet.

We also remove tailer spaces in the PHP files so I actually have another alias that removes all trailing spaces which I end up having to use if I miss some, as I have a git-pre-commit script which actually runs through lint/spacing/php checks to make sure I'm committing the right things.

If you want to run a pre-check there is a style script check in the bin folder.