The task here is to review/fix all of the AsciiDoc source files, and check for the following AsciiDoc formatting concerns:
- The formatting of the headers, subheaders, lists, etc. works (no wrong numbers, etc.). Images do not spill out of margins; narrow images are not artificially widened (you may need to take out or add
,width="100%"
in image tags). - Text should be wrapped in lines going out to around 80-characters, without going over, as much as possible. However, lines specifying images, links, and the like can go over 80 characters to keep the image/link, including attributes, all together on one line.
- When formatting a bullet list or numbered list, within each list item, subsequent lines should start at the left margin. Paragraph breaks within a list item are generated by + signs. Example:
. This is a numbered list item. After reaching the 80 character line length, the next line starts at the left margin. + And this is a second paragraph within the same list item.
- All of the sections from the appropriate template should be present in both Task and Concept topics. If they are empty, they should be commented out:
// ==== Site prerequisites
- Within a particular section, such as Steps, if a sub-heading is needed, it uses ===== notation rather than just being a sentence in bold or some ad-hoc formatting like that.
- We don't need a heading at the top of Steps that just repeats the Goal. Just remove it.
- Bullet lists should never have just one item. Take out the bullet if so.
Status
As of 15 Feb, all the topics that had been written to this point have been checked over for formatting.
The following files were skipped because they were not written yet, so they still need to be reviewed/fixed:
extend-config-versions.txt
extend-manual-install.txt
install-dev-making.txt
planning-layout.txt
structure-pathauto.txt
In addition, when editing for problems identified in testing or copy-editing, or replacing images, we'll need to keep in mind the AsciiDoc formatting (80-character lines etc.) and also check the output to make sure the screen shots still look OK on the page, numbering works, etc. So this will probably need a final review.
Comments
Comment #2
jhodgdonI'm going to take care of this now, in several separate commits (in alphabetical groups of file names). It should be all whitespace and AsciiDoc formatting marks, no text changes.
There are a few topics that aren't finished yet. So when the current files are finalized, we should also go through the git commit log and review/fix the topics that are touched after the first pass is done.
Comment #3
jhodgdonAdded two more things to the issue summary to look for.
The first commit covers files starting with A-C:
attributions.txt
block-concept.txt (no changes needed)
block-create-custom.txt
block-place.txt
block-regions.txt [had to rearrange things slightly to make the sections of Steps work]
config-basic.txt
config-overview.txt
config-theme.txt [had to make a table in one area that was previously some unformatted lines]
config-uninstall.txt
config-user.txt
content-create.txt
content-edit.txt
content-paths.txt (no changes needed)
copyright.txt (no changes needed)
Files skipped (not written yet):
content-in-place-edit.txt
Comment #5
jhodgdonThe next review/fix/commit is E-I files:
extend-module-find.txt
extend-theme-find.txt
extend-theme-install.txt
glossary.txt (no changes needed)
guide.txt - this is the overall guide chapter/topic structure, skipped this
install-dev-sites.txt
install-prepare.txt -- this required a small amount of reorganization
install-requirements.txt
install-run.txt
I also realized there was something weird going on with the "Fields and values" tables, that was making them appear in the TOC. I fixed the guidelines file good-writing.txt, and went back and also fixed this on config-basic.txt from the last commit.
Note: Some files were skipped because they are not written yet -- added these to issue summary directly.
Comment #7
jhodgdonNext patch is L-M:
language-add.txt [also took care of a To Do note in this topic]
language-concept.txt (no changes needed)
language-content-config.txt
language-enable.txt
menu-concept.txt (no changes needed)
menu-home.txt (also removed duplicate image that added no value)
menu-link-from-content.txt (slight reorganization of two of the steps was needed)
menu-reorder.txt
Note: Some files were skipped because they are not written yet -- added these to issue summary directly.
Comment #10
jhodgdonAnother chunk: just the letter P
planning-data-types.txt
planning-structure.txt
planning-workflow.txt
preface-audience.txt
preface-conventions.txt
preface-organization.txt (no changes needed)
preface-scenario.txt
prevent-backups.txt
prevent-cache.txt
prevent-cache-clear.txt
prevent-log.txt
prevent-status.txt
Also went back and made sure I had actually looked at the output for the ones marked "no changes needed" in previous batches, and decided this one needed some small formatting changes:
menu-concept.txt
Note: Some files were skipped because they are not written yet -- added these to issue summary directly.
Comment #11
jhodgdonTwo chunks to go! I'll do the letter S here, and then there will be T-U-V. This one:
security-announce.txt
security-concept.txt (no changes needed)
security-cron.txt (required slight reorganization near the end to get the formatting right)
security-cron-concept.txt
security-update-core.txt (slight reorganization in a few places to get the formatting right)
structure-adding-reference.txt
structure-content-display.txt
structure-content-type.txt
structure-content-type-delete.txt
structure-fields.txt
structure-form-editing.txt
structure-image-responsive.txt
structure-image-style-create.txt
structure-image-styles.txt
structure-reference-fields.txt
structure-taxonomy.txt (no changes needed)
structure-taxonomy-setup.txt (small reorg needed of one step for formatting)
structure-text-formats.txt
structure-view-modes.txt
structure-widgets.txt
Note: Some files were skipped because they are not written yet -- added these to issue summary directly.
Comment #13
jhodgdonextend-module-install got written; also I reviewed the changes to security-cron made since I went over it (no changes needed).
Comment #16
jhodgdonLast chunk: T-U-V.
thoughts-learn-more.txt
understanding-data.txt (no changes needed)
understanding-distributions.txt
understanding-drupal.txt
understanding-gpl.txt
understanding-modules.txt
understanding-project.txt
understanding-themes.txt
user-admin-account.txt
user-concept.txt
user-content.txt
user-new-role.txt
user-new-user.txt
user-permissions.txt
user-roles.txt
views-concept.txt
views-parts.txt
Leaving this issue open because there were some skipped files (topics not written yet; some added to summary within this group).
Comment #18
jhodgdonFixed up two recent additions.
Comment #19
jhodgdonTwo more recent additions fixed up a bit. Hah. Both were topics I wrote and they still had minor fixups. ;)
Comment #22
jhodgdonsecurity-update-module taken care of. Required a small amount of reorganization of the first step. Also I had forgotten to commit the image when I added that one to the guide a few minutes ago, whoops. All taken care of.
Comment #23
jhodgdonTook care of new topics views-duplicate.txt.
Comment #26
jhodgdonTook care of structure-text-format-config.txt.
Comment #27
jhodgdonTook care of two new ones:
extend-maintenance.txt
security-update-theme.txt
Comment #29
jhodgdonTook care of 3 more topics: views-create, extend-deploy, and views-block.
Comment #31
jhodgdonFixing topic list.
Comment #32
jhodgdonTook care of very minor stuff in language-content-translate when I committed the topic at first.
Comment #33
jhodgdonTook care of language-config-translate when I committed it (very minor stuff).
Comment #34
jhodgdonplanning-modular also checked over at commit.
Comment #35
jhodgdonplanning-layout is done.
Comment #37
jhodgdonThe only thing left now is
install-dev-making.txt
Comment #39
jhodgdonI'm writing install-dev-making, so I think this is done.