Skip to contentSkip to conversation

Docs/mm: rename legacy docs to unsorted docs

PATCH In review SeongJae Park 4 participants 13 messages Jul 1, 2024 – Jul 4, 2024

Subsystems (4)
lore
Share & tools
lore
#0 lore raw

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
#1 lore raw

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
index d3b733b41ae6..ffd6655b7be2 100644
@@ -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
#3 lore raw

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
index 48b9b559ca7b..5007815405f1 100644
@@ -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
#4 lore raw

PATCH 3/4 Docs/mm/index: rename 'Legacy Documentation' to 'Unsorted Documentation'

In reply to SeongJae Park

The 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
index 5007815405f1..15614df2b989 100644
@@ -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
#5 lore raw

PATCH 4/4 Docs/mm/index: move allocation profiling document to unsorted documents chapter

In reply to 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.

---
 Documentation/mm/index.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/mm/index.rst +1 -1
index 15614df2b989..0be1c7503a01 100644
@@ -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
maintainer Acked-by on v1 1/4
#2 lore raw

Re: [PATCH 1/4] Docs/mm/allocation-profiling: mark 'Theory of operation' as chapter

In reply to SeongJae Park
Quoted 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.

Quoted 19 lines
---
 Documentation/mm/allocation-profiling.rst | 1 -
 1 file changed, 1 deletion(-)
Documentation/mm/allocation-profiling.rst +0 -2
index d3b733b41ae6..ffd6655b7be2 100644
@@ -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

maintainer
#6 lore raw

Re: [PATCH 4/4] Docs/mm/index: move allocation profiling document to unsorted documents chapter

In reply to SeongJae Park
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.

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

maintainer
#12 lore raw
In reply to SeongJae Park
Quoted 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

#7 lore raw

Re: [PATCH 4/4] Docs/mm/index: move allocation profiling document to unsorted documents chapter

In reply to Jonathan Corbet
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 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

[...]

#8 lore raw

Re: [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

[...]

reviewer
#9 lore raw

Re: [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_owner and 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
#10 lore raw

Re: [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_owner and 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 under Documentation/mm/, that is.

I think it belongs more to mm than dev-tools TBH.

Quoted 3 lines

--
~Randy

#11 lore raw

Re: [PATCH 4/4] Docs/mm/index: move allocation profiling document to unsorted documents chapter

In reply to Suren Baghdasaryan
Quoted 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_owner and 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

[...]