Docs/mm: rename legacy docs to unsorted docs
Subsystems (4)
cover Docs/mm: rename legacy docs to unsorted docs
The work for changing the memory mangement documentation outline has started from 2022. For that, old documents have placed under new chapter, "Legacy Documentations". The plan is to eventually move all old documentations into new outline, while asking new documents to be added on the new outline from the beginning.
However, it is unclear where on the new outline each document should be placed for some cases. Meanwhile, the name ("legacy") makes readers feel the documents under the chapter might be outdated or not actively maintained. The absence of clear criteria for new outline also makes new documents difficult to find where those should be placed. A new document was put on the bottom of the new outline recently, apparently not based on a clear guideline but just because it is the bottom of the list.
Rename the "Legagy Documentation" chapter to "Unsorted Documentations" with minor fixups.
SeongJae Park (4):
Docs/mm/allocation-profiling: mark 'Theory of operation' as chapter Docs/mm/index: Remove 'Memory Management Guide' chapter marker Docs/mm/index: rename 'Legacy Documentation' to 'Unsorted
Documentation'
Docs/mm/index: move allocation profiling document to unsorted
documents chapter
Documentation/mm/allocation-profiling.rst | 1 - Documentation/mm/index.rst | 19 ++++++++----------- 2 files changed, 8 insertions(+), 12 deletions(-)
base-commit: 5dc709e59ba6486e519b22f86278c978b422a025
Signature · 1 line
2.39.2
PATCH 1/4 Docs/mm/allocation-profiling: mark 'Theory of operation' as chapter
'Theory of operation' part of allocation-profiling document is apparently a chapter. However, it is mistakenly marked as a document title. As a result, rendered mm document index page shows two items for the document. Fix it to be marked as a chapter.
--- Documentation/mm/allocation-profiling.rst | 1 - 1 file changed, 1 deletion(-)
Documentation/mm/allocation-profiling.rst +0 -1
@@ -46,7 +46,6 @@ Example output:: 55M 4887 mm/slub.c:2259 func:alloc_slab_page 122M 31168 mm/page_ext.c:270 func:alloc_page_ext -=================== Theory of operation ===================
Signature · 1 line
2.39.2
PATCH 2/4 Docs/mm/index: Remove 'Memory Management Guide' chapter marker
In reply to SeongJae Park'Memory Management Guide' chapter aims to be not an additional chapter of the document, but the ultimate single outline of the document. In the sense, marking it as a chapter under the document makes no sense, and the rendered document looks odd. Remove the chapter marker.
--- Documentation/mm/index.rst | 3 --- 1 file changed, 3 deletions(-)
Documentation/mm/index.rst +0 -3
@@ -2,9 +2,6 @@ Memory Management Documentation =============================== -Memory Management Guide -======================= - This is a guide to understanding the memory management subsystem of Linux. If you are looking for advice on simply allocating memory, see the :ref:`memory_allocation`. For controlling and tuning guides,
Signature · 1 line
2.39.2
PATCH 3/4 Docs/mm/index: rename 'Legacy Documentation' to 'Unsorted Documentation'
In reply to SeongJae ParkThe intention of 'Legacy Documentation' chapter is to keep the old documents that not yet sorted into the new outline, and encourage new documents to be integrated in the new outline from the beginning.
However, the new outline will take some more time to be completed. It has started about two years ago, and still many parts are not yet written. Also, there is no clear guidline for placing each document for all cases, for not only the 'legacy' documents, but also for new documents. For example, memory allocation profiling document has been added to the bottom of the new outline. Apparently it was not following some well-defined guideliens or a result of a discussion.
Furthermore, the title ("legacy") makes people feel the documents on the chapter might be outdated or not actively maintained.
Rename 'Legacy Documentation' to 'Unsorted Documentation' and remove the description saying it is for 'older' documents. After this change, new documents that not clear enough where it should be placed on the new outline can be added on the chapter while well-defined guidelines or discussion for the new outline is made.
--- Documentation/mm/index.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-)
Documentation/mm/index.rst +7 -7
@@ -25,14 +25,14 @@ see the :doc:`admin guide <../admin-guide/mm/index>`. oom allocation-profiling -Legacy Documentation -==================== +Unsorted Documentation +====================== -This is a collection of older documents about the Linux memory management -(MM) subsystem internals with different level of details ranging from -notes and mailing list responses for elaborating descriptions of data -structures and algorithms. It should all be integrated nicely into the -above structured documentation, or deleted if it has served its purpose. +This is a collection of unsorted documents about the Linux memory management +(MM) subsystem internals with different level of details ranging from notes and +mailing list responses for elaborating descriptions of data structures and +algorithms. It should all be integrated nicely into the above structured +documentation, or deleted if it has served its purpose. .. toctree:: :maxdepth: 1
Signature · 1 line
2.39.2
PATCH 4/4 Docs/mm/index: move allocation profiling document to unsorted documents chapter
In reply to SeongJae ParkThe memory allocation profiling document was added to the bottom of the new outline. Apparently it was not decided by well-defined guidelines or a thorough discussions. Rather than that, it was added there just because there was no place for such unsorted documents. Now there is the chapter. Move the document to the new place.
--- Documentation/mm/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/mm/index.rst +1 -1
@@ -23,7 +23,6 @@ see the :doc:`admin guide <../admin-guide/mm/index>`. page_cache shmfs oom - allocation-profiling Unsorted Documentation ======================
@@ -38,6 +37,7 @@ documentation, or deleted if it has served its purpose. :maxdepth: 1 active_mm + allocation-profiling arch_pgtable_helpers balance damon/index
Signature · 1 line
2.39.2
Re: [PATCH 1/4] Docs/mm/allocation-profiling: mark 'Theory of operation' as chapter
In reply to SeongJae ParkQuoted 7 lines · SeongJae Park
'Theory of operation' part of allocation-profiling document is apparently a chapter. However, it is mistakenly marked as a document title. As a result, rendered mm document index page shows two items for the document. Fix it to be marked as a chapter.
Signed-off-by SeongJae Park <[email protected]>
Quoted 19 lines
--- Documentation/mm/allocation-profiling.rst | 1 - 1 file changed, 1 deletion(-)Documentation/mm/allocation-profiling.rst +0
-2@@ -46,7 +46,6 @@ Example output:: 55M 4887 mm/slub.c:2259 func:alloc_slab_page 122M 31168 mm/page_ext.c:270 func:alloc_page_ext -=================== Theory of operation =================== --2.39.2
Jonathan Corbet
maintainerRe: [PATCH 4/4] Docs/mm/index: move allocation profiling document to unsorted documents chapter
In reply to SeongJae ParkQuoted 5 lines · SeongJae Park
The memory allocation profiling document was added to the bottom of the new outline. Apparently it was not decided by well-defined guidelines or a thorough discussions. Rather than that, it was added there just because there was no place for such unsorted documents. Now there is the chapter. Move the document to the new place.
I'll take this for now, but it's truly sad to see new documentation being added to the slushpile at the end. It seems better to create a "development tools" section in the new outline and put the allocation profiling document there?
Thanks,
jon
Jonathan Corbet
maintainerQuoted 15 lines · SeongJae Park
The work for changing the memory mangement documentation outline has started from 2022. For that, old documents have placed under new chapter, "Legacy Documentations". The plan is to eventually move all old documentations into new outline, while asking new documents to be added on the new outline from the beginning.
However, it is unclear where on the new outline each document should be placed for some cases. Meanwhile, the name ("legacy") makes readers feel the documents under the chapter might be outdated or not actively maintained. The absence of clear criteria for new outline also makes new documents difficult to find where those should be placed. A new document was put on the bottom of the new outline recently, apparently not based on a clear guideline but just because it is the bottom of the list.
Quoted 2 lines
Rename the "Legagy Documentation" chapter to "Unsorted Documentations" with minor fixups.
Series applied, thanks.
jon
Re: [PATCH 4/4] Docs/mm/index: move allocation profiling document to unsorted documents chapter
In reply to Jonathan CorbetQuoted 8 lines · On Wed, 03 Jul 2024 16:18:42 -0600 Jonathan Corbet <[email protected]> wrote:
Quoted 5 lines · SeongJae Park
The memory allocation profiling document was added to the bottom of the new outline. Apparently it was not decided by well-defined guidelines or a thorough discussions. Rather than that, it was added there just because there was no place for such unsorted documents. Now there is the chapter. Move the document to the new place.
Quoted 4 lines
I'll take this for now, but it's truly sad to see new documentation being added to the slushpile at the end. It seems better to create a "development tools" section in the new outline and put the allocation profiling document there?
I have no strong opinions about that. Cc-ing Suren and Kent, as they are the author of the allocation profiling document and hence might have some opinion.
Thanks,
SJ
[...]
Suren Baghdasaryan
maintainerRe: [PATCH 4/4] Docs/mm/index: move allocation profiling document to unsorted documents chapter
Quoted 11 lines · SeongJae Park
Quoted 8 lines · On Wed, 03 Jul 2024 16:18:42 -0600 Jonathan Corbet <[email protected]> wrote:
Quoted 5 lines · SeongJae Park
The memory allocation profiling document was added to the bottom of the new outline. Apparently it was not decided by well-defined guidelines or a thorough discussions. Rather than that, it was added there just because there was no place for such unsorted documents. Now there is the chapter. Move the document to the new place.
Quoted 7 lines
Quoted 4 lines
I'll take this for now, but it's truly sad to see new documentation being added to the slushpile at the end. It seems better to create a "development tools" section in the new outline and put the allocation profiling document there?
I have no strong opinions about that. Cc-ing Suren and Kent, as they are the author of the allocation profiling document and hence might have some opinion.
IMHO if this would be the only document belonging to "development tools" then keeping it under unsorted is fine.
If more documents will fall into that category then Jonathan's suggestion makes sense to me. Looking at the current list, page_owner and maybe damon might be considered for this category as well. SeongJae, WDYT?
Thanks,
Suren.
Quoted 6 lines
Thanks,
SJ[...]
Randy Dunlap
reviewerRe: [PATCH 4/4] Docs/mm/index: move allocation profiling document to unsorted documents chapter
Quoted 20 lines · Suren Baghdasaryan
Quoted 11 lines · SeongJae Park
Quoted 8 lines · On Wed, 03 Jul 2024 16:18:42 -0600 Jonathan Corbet <[email protected]> wrote:
Quoted 5 lines · SeongJae Park
The memory allocation profiling document was added to the bottom of the new outline. Apparently it was not decided by well-defined guidelines or a thorough discussions. Rather than that, it was added there just because there was no place for such unsorted documents. Now there is the chapter. Move the document to the new place.
Quoted 7 lines
Quoted 4 lines
I'll take this for now, but it's truly sad to see new documentation being added to the slushpile at the end. It seems better to create a "development tools" section in the new outline and put the allocation profiling document there?
I have no strong opinions about that. Cc-ing Suren and Kent, as they are the author of the allocation profiling document and hence might have some opinion.
Quoted 9 lines
IMHO if this would be the only document belonging to "development tools" then keeping it under unsorted is fine.
If more documents will fall into that category then Jonathan's suggestion makes sense to me. Looking at the current list,page_ownerand maybe damon might be considered for this category as well. SeongJae, WDYT?
Thanks,
Suren.
Documentation/dev-tools/ already contains 20 files. Unless you want to keep it under Documentation/mm/, that is.
Signature · 1 line
~Randy
Suren Baghdasaryan
maintainerRe: [PATCH 4/4] Docs/mm/index: move allocation profiling document to unsorted documents chapter
Quoted 34 lines · Randy Dunlap
Quoted 20 lines · Suren Baghdasaryan
Quoted 11 lines · SeongJae Park
Quoted 8 lines · On Wed, 03 Jul 2024 16:18:42 -0600 Jonathan Corbet <[email protected]> wrote:
Quoted 5 lines · SeongJae Park
The memory allocation profiling document was added to the bottom of the new outline. Apparently it was not decided by well-defined guidelines or a thorough discussions. Rather than that, it was added there just because there was no place for such unsorted documents. Now there is the chapter. Move the document to the new place.
Quoted 7 lines
Quoted 4 lines
I'll take this for now, but it's truly sad to see new documentation being added to the slushpile at the end. It seems better to create a "development tools" section in the new outline and put the allocation profiling document there?
I have no strong opinions about that. Cc-ing Suren and Kent, as they are the author of the allocation profiling document and hence might have some opinion.
Quoted 9 lines
IMHO if this would be the only document belonging to "development tools" then keeping it under unsorted is fine.
If more documents will fall into that category then Jonathan's suggestion makes sense to me. Looking at the current list,page_ownerand maybe damon might be considered for this category as well. SeongJae, WDYT?
Thanks,
Suren.
Quoted 2 lines
Documentation/dev-tools/already contains 20 files. Unless you want to keep it underDocumentation/mm/, that is.
I think it belongs more to mm than dev-tools TBH.
Quoted 3 lines
--
~Randy
Re: [PATCH 4/4] Docs/mm/index: move allocation profiling document to unsorted documents chapter
In reply to Suren BaghdasaryanQuoted 20 lines · On Wed, 3 Jul 2024 19:10:03 -0700 Suren Baghdasaryan <[email protected]> wrote:
Quoted 11 lines · SeongJae Park
Quoted 8 lines · On Wed, 03 Jul 2024 16:18:42 -0600 Jonathan Corbet <[email protected]> wrote:
Quoted 5 lines · SeongJae Park
The memory allocation profiling document was added to the bottom of the new outline. Apparently it was not decided by well-defined guidelines or a thorough discussions. Rather than that, it was added there just because there was no place for such unsorted documents. Now there is the chapter. Move the document to the new place.
Quoted 7 lines
Quoted 4 lines
I'll take this for now, but it's truly sad to see new documentation being added to the slushpile at the end. It seems better to create a "development tools" section in the new outline and put the allocation profiling document there?
I have no strong opinions about that. Cc-ing Suren and Kent, as they are the author of the allocation profiling document and hence might have some opinion.
Quoted 6 lines
IMHO if this would be the only document belonging to "development tools" then keeping it under unsorted is fine.
If more documents will fall into that category then Jonathan's suggestion makes sense to me. Looking at the current list,page_ownerand maybe damon might be considered for this category as well. SeongJae, WDYT?
I agree it makes more sense to have multiple documents under dedicated sections. And putting page_owner sounds not that odd to me.
DAMON is, however, not a tool but a framework that helps easy development of access-aware kernel components. Such components could be development tools and system operations optimizations (using DAMOS). So, IMHO, 'development tools' section is not the perfect place for DAMON documents.
Actually, even for allocation-profiling and page_owner, I think 'development tools' might not be a perfect category. I understand those as features that could be useful for system investigations of multiple purposes.
So, in short, I think it is not easy to find a perfect cateogry...
Thanks,
SJ
[...]