Cppcoreguidelines: Give a split view of the Guidelines when vied on a phone by chapters.

[AraHaan]

I would like each and every entry have separate files for the following reasons:

• cannot view the guidelines in phone based devices without the phone we freezing for a long time making the phone battery to get drained and wasted considerably. Some people like me read the guidelines when they are not on an actual desktop or laptop computer.
• Makes editing everything a lot easier and faster without scrolling through thousands of millions of lines just to find the right place to make changes. This makes patches to things a lot faster.

Yes, I know the drawback of this is maybe hundreds or thousands of markdown file but each guideline markdown file would be the name that is selected for them for example c. 140 would be 'c140.md'.

[jwakely]

Makes editing everything a lot easier and faster without scrolling through thousands of millions of lines just to find the right place to make changes.

Your text editor should have a search function to make scrolling unnecessary.

[AraHaan]

Not when viewing this on github on iOS and android based devices because you are far from your computer. Also some people use github for editing and some editors do not have an find function. And other cases some devices have no editor at all forcing the use of GitHub's one. There was a time I wanted to edit something on this on my iPhone but could not because the freezes was draining the battery very fast even on low power mode. And you might be wondering why I wanted to because my laptop had no electricity and internet and so my iPhone was only means to edit it.

[jwakely]

Also some people use github for editing

The browser's "find" function works within the page even when using the github web-based editor.

and some editors do not have an find function.

I find that hard to believe.

If the real problem is browsing the guidelines on mobile devices then a better solution might be to have an alternative rendering of them for mobile browsing. e.g. have http://isocpp.github.io/CppCoreGuidelines/mobile go to a different copy which is split up into separate pages.

The downside of doing that for all users is that it's no longer possible to search the single-page version to find every occurrence of a word or phrase. Having two versions means people can choose which to use at any given time.

[AraHaan]

Yeah that would help a lot too. That page right now gives not found though.

[galik]

I don't know about every single item but it might be nice to split up the different sections?

[AraHaan]

Yeah that is definitely true

[magol]

I totally agree with this issue.
For me, it's almost impossible to read or edit the page on my phone.
I suggest that everything is split into separate MD files to simplify editing (for the same reason you do not want you whole C++ program in a single file)
Then I suggest that on the homepage you can choose whether to view all content on a single page or broken down by headlines.

[AraHaan]

Yeah, not to mention markdown and restructuredtext supports and renders HTML so you can use an simple HTML tag to make it look like it is 1 single file easily. As such I could pull request the changes if need be when I am on my laptop again. And yes I used HTML before to link and embed other files in it. At least it works that way.

[scraimer]

Having just gone through the process of pushing a pull request, I cannot imagine editing the guidelines on a phone.

None of the scripts for enforcing code style and spelling are readily available through my phone. Every Travis CI build would fail until each detail was fixed.
Doing so many iterations sounds painful, and a bit too embarrassing for my taste.

But if either of you build a system to handle that, post it here. I'd love to try it!

[AndrewPardoe]

Per our editor's discussion, and for the reasons @jwakely commented on above, we are not inclined to split the Guidelines file.

[magol]

@AndrewPardoe,
I completely agree that it is not smart to edit CppCoreGuidelines.md on a mobile phone. And, as I see it, that's not what this problem is about.

The problem is that the page is so heavy that Chrome on my mobile phone is freezing or crashing. It's simply impossible to read the page on my mobile phone.

I would like to rephrase the problem description and reopen the issue. It does not matter if CppCoreGuidelines.md is divided into separate files, but I would like to have the opportunity to choose whether I want to see the site as it is now or divided by chapters.

[AraHaan]

It does it in Firefox on my phone too. And even on Safari that comes preinstalled on the iPhone...

[galik]

For those interested I have a utility to split the guidelines into separate files per section that can be found here:
https://github.com/galik/CppCoreGuidelines/tree/extract-sections/contrib

I will shortly write a cron job to keep the sections up to date with the origin/master. The sections can be found here:
https://github.com/galik/CppCoreGuidelines/tree/extract-sections/sections

The internal index can be found here:
https://github.com/galik/CppCoreGuidelines/blob/extract-sections/sections/00-In-Introduction.md#SS-sec

[AraHaan]

This is much better. Thanks

[jwakely]

As stated above, we are not interested in supporting editing on phones, but we are interested in being able to read on phones, and embedded within other tools (like editors or IDEs). For the latter purpose one page per guideline would be preferable.

@galik would you be willing to polish up your utility and create a pull request to upstream this, so we can have different renderings in the official location? (ideally split by chapter and also by guideline). An external copy of the docs is not ideal, in case your cronjob breaks or stops for some reason.

[galik]

@jwakely Yes, I'm working on a version that splits out the individual items too, I can't wait to make random guidelines my MOTD.

[MikeGitb]

On a related note: I can't even use githubs integrated git blame on firefox on my desktop machine.

[robert-andrzejuk]

@galik How is it progressing?

[galik]

@robert-andrzejuk

I did do some work on this.

However I gave up for a few reasons. The code I was producing was overly complex and hard to maintain. The structure of the document is regular but easily susceptible to minor irregularities introduced by human editors. I cleared a bunch of those up through PRs but it would obviously be an ongoing problem. Some of them, however, were waiting on the official authors to finish parts that might not get finished for some time. Also I had not realized before that the document contains both sections and subsections. This makes things more difficult. Would I just consider subsections as regular sections? Or would I introduce depth to the resulting parts? Another problem is the document contains explicit indexes and should I just convert the explicit ones or build a (likely more accurate?) implicit index based on actual structure? What if the two differ?

I came to the conclusion that if I were to do this properly, I would want the document to be in stricter format. Probably some simple XML schema. Then you could force every entry to conform to a rigid template. It is a fantastic idea to be able to provide item by item access to the guidelines. Unfortunately I just found too many gotchas with the current format. I know others have requested the original document to be in other formats but that has met with resistance. So I don't expect that to change any time soon.

Maybe someone else can take up this challenge? It is still something I would very much like to have.

For those interested my latest efforts can be found here:
https://github.com/galik/CppCoreGuidelines/blob/contrib-extract-sections/contrib/extract-sections.cpp

You may be able to salvage the odd regular expression.

[pandysong]

I wrote a small script to parse markdown file, and filter out the rules:
out.txt

Is anyone still interested in splitting to a small markdown files (Specifically to split rules to separate files)?

I personally find it really takes much time on my VIM to open the original md file (maybe because it has some markdown plugin installed).

[pandysong]

BTW, In case anyone interested in small markdown files, here is the initial version:

https://github.com/pandysong/CppCoreGuidelines_SmallFiles/blob/master/guidelines/01_main.md

I spend some time to write a small script to split the big file to small files and also resolve/replace the links.

[pandysong]

For whoever interested:
The source code to parse and split the big markdown to small pieces:

https://github.com/pandysong/md_parser

With the parser provided, it is also possible to write code which could generate other more fancy form of pages.