Opened 7 months ago

Last modified 4 months ago

#33741 new enhancement

Format code blocks inside markdown files (documentation)

Reported by: bduszel Owned by:
Priority: Very Low Milestone: Tor: unspecified
Component: Core Tor/Tor Version:
Severity: Minor Keywords: doc, easy, 044-deferred
Cc: Actual Points:
Parent ID: Points:
Reviewer: Sponsor:


There are issues with code blocks inside some *.md files (some files use code blocks syntax, some do not). First of all, it's not consistent but what's really bad is when *.md file is being displayed incorrectly. You can find an example of what I'm saying in under How we log changes section.

Part of the git log output is still displayed as a regular text rather than a formatted code block.

Goal of this ticket is to go through all *.md files under doc and doc/HACKING directories and format code snippets accordingly.

// code snippet
// written in
// C language
// command to be run
// inside bash

This should fix the issues described above and enable syntax highlighting on supported websites and editors.

Child Tickets

Change History (4)

comment:1 Changed 7 months ago by nickm

I wonder if there's some way to automate this change, at least heuristically.

comment:2 Changed 7 months ago by bduszel

We could start by looking for code blocks without language specified.

// bash code


// bash code

Another check could be to search for all the lines starting with $ and making sure these are inside bash code blocks. This approach won't work for code blocks with command output though:

$ git describe --contains ebab521525 // only this line would be recognized

However such search would at least let us know where commands are being used and what we should check manually.

No idea how to recognize the following scenario though:

If you're writing an assertion to test for a bug that you _can_ recover from,
use `tor_assert_nonfatal()` in place of `tor_assert()`.  If you'd like to
write a conditional that incorporates a nonfatal assertion, use the `BUG()`
macro, as in:

        if (BUG(ptr == NULL))
                return -1;

## Allocator conventions

comment:3 Changed 7 months ago by dgoulet

Milestone: Tor: 0.4.4.x-final

comment:4 Changed 4 months ago by nickm

Keywords: 044-deferred added
Milestone: Tor: 0.4.4.x-finalTor: unspecified

Bulk-remove tickets from 0.4.4. Add the 044-deferred label to them.

Note: See TracTickets for help on using tickets.