Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Intro to style guidelines, add section about <simpara> #168

Merged
merged 1 commit into from
Oct 23, 2024
Merged

Intro to style guidelines, add section about <simpara> #168

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 16 additions & 0 deletions docs/style.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,13 @@
# Style guidelines

The style for the PHP manual has evolved over the years, and this tries
to capture the current guidelines. Existing documentation may not closely
adhere to these, but new additions and substantial changes should.

When updating existing documentation, it is okay to not update
conflicts with these style guidelines if it would cause too much work
for translators.

## Technical requirements
- All files **must** be encoded using UTF-8 (without BOM)
- Use only Unix line endings (`\n`)
Expand All @@ -24,6 +32,14 @@ a period.
Sentences need not have two spaces between them.
Commas and apostrophes should be used appropriately.

## Markup

### Use `<para>` sparingly

Use `<simpara>` in markup (similar to HTML's `<p>`) in favor of `<para>`
(similar to HTML's `<div>`) when there are no block elements (such as
`<example>` or `<itemizedlist>` in the paragraph.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So that's the difference between the two! TIL...


## Personalization
The PHP Manual is a technical document, and should be written so. The use of "you" is rampant in the manual,
and presents an unprofessional image. The only exceptions to the personalization rule are: the PHP Tutorial and FAQs.
Expand Down
Loading